basecamp/kamal · error · RuntimeError

Passbolt CLI is not installed

Error message

Passbolt CLI is not installed

What it means

Kamal calls check_dependencies! before using the Passbolt adapter; it probes `passbolt --version` and raises this error (passbolt.rb:122) when the exit status is non-zero, i.e. no working `passbolt` executable is on PATH. It is a hard precondition: no passbolt secret can be fetched until the CLI is installed and invocable by the same environment that runs Kamal.

Source

Thrown at lib/kamal/secrets/adapters/passbolt.rb:122

      found_paths = all_folders.map { |f| get_folder_path(f, all_folders) }
      missing_paths = folder_paths.map { |path| path.join("/") } - found_paths
      raise RuntimeError, "Could not find the following folders in Passbolt: #{missing_paths.join(", ")}" if missing_paths.any?

      all_folders
    end

    def get_folder_path(folder, all_folders, path = [])
      path.unshift(folder["name"])
      return path.join("/") if folder["folder_parent_id"].to_s.empty?

      parent = all_folders.find { |f| f["id"] == folder["folder_parent_id"] }
      return path.join("/") unless parent

      get_folder_path(parent, all_folders, path)
    end

    def check_dependencies!
      raise RuntimeError, "Passbolt CLI is not installed" unless cli_installed?
    end

    def cli_installed?
      `passbolt --version 2> /dev/null`
      $?.success?
    end
end

View on GitHub (pinned to eee0083b38)

Solutions

  1. Install the passbolt CLI on the machine that runs Kamal, and verify with `passbolt --version`.
  2. Ensure the binary is on PATH for the exact user and context invoking kamal; for cron/systemd use an absolute PATH or symlink the binary into /usr/local/bin.
  3. Re-run `passbolt configure` after installing so credentials and server config exist.
  4. Add a CI step that fails fast when `command -v passbolt` returns nothing.

Example fix

// before
$ kamal deploy
RuntimeError: Passbolt CLI is not installed

// after
# install the passbolt CLI for your platform, then:
$ passbolt --version && passbolt configure
$ command -v passbolt   # e.g. /usr/local/bin/passbolt
$ kamal deploy
Defensive patterns

Strategy: validation

Validate before calling

# Fail fast before any passbolt-dependent Kamal task
system('passbolt --version >/dev/null 2>&1') or abort('Passbolt CLI is not installed — install it and run `passbolt configure`')

Prevention

When it happens

Trigger: Using any `passbolt/...` secret reference (kamal secrets fetch, kamal deploy, kamal env push) on a machine where the passbolt CLI binary is absent, not executable, or not on PATH for the invoking user or shell — common in CI containers, cron jobs, systemd units, and freshly provisioned machines.

Common situations: Fresh dev machine or CI image without the CLI; the CLI installed via a version manager (rbenv/asdf) that is not activated in the deploy shell; PATH stripped or overridden by cron/systemd; binary installed under a different name or only for another user.

Related errors

AI-assisted analysis of basecamp/kamal@eee0083b38 (2026-08-21). Data as JSON: /api/errors/241ca0e84b46cf2b. Report an issue: GitHub.