What causes "Doppler CLI is not installed" in basecamp/kamal?

Install the CLI: `brew install dopplerhq/cli/doppler` (macOS/Linux) or curl -Ls https://cli.doppler.com/install.sh | sh, then confirm `doppler --version` works in the same environment that runs kamal.

basecamp/kamal · error · RuntimeError

Doppler CLI is not installed

Error message

Doppler CLI is not installed

What it means

Raised by check_dependencies! in Kamal::Secrets::Adapters::Doppler when `doppler --version 2> /dev/null` exits non-zero, i.e. the Doppler CLI binary is not usable on PATH. Base#fetch always runs this dependency probe before login/fetch_secrets, so the error appears regardless of token state.

Source

Thrown at lib/kamal/secrets/adapters/doppler.rb:50

    def secrets_get_flags(secrets)
      unless service_token_set?
        project, config, _ = secrets.first.split("/")

        unless project && config
          raise RuntimeError, "Missing project or config from '--from=project/config' option"
        end

        project_and_config_flags = "-p #{project.shellescape} -c #{config.shellescape}"
      end
    end

    def service_token_set?
      ENV["DOPPLER_TOKEN"] && ENV["DOPPLER_TOKEN"][0, 5] == "dp.st"
    end

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

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

View on GitHub (pinned to eee0083b38)

Solutions

Install the CLI: `brew install dopplerhq/cli/doppler` (macOS/Linux) or curl -Ls https://cli.doppler.com/install.sh | sh, then confirm `doppler --version` works in the same environment that runs kamal.
If installed but not found, add its install dir to PATH for the kamal process (CI step, Dockerfile ENV, or shell profile).
Pin the install in your provisioning scripts so fresh deploy boxes get it automatically.

Defensive patterns

Strategy: validation

Validate before calling

require "open3"

def doppler_installed?
  Open3.capture3("doppler", "--version")[2].success?
end

abort "Install the Doppler CLI (brew install dopplerhq/cli/doppler)" unless doppler_installed?

Prevention

Install doppler CLI in the image/CI that runs kamal; assert with `which doppler` in a preflight step.
Bake the install into Dockerfile so fresh runners are consistent.
Watch PATH in cron/systemd contexts where user-local installs are invisible.

When it happens

Trigger: adapter.fetch(...) (e.g. `kamal secrets pull` with the doppler adapter) on a host where `doppler` is absent from PATH: not installed, installed under a user-local path not in the kamal process's PATH, or a broken binary.

Common situations: CI images without the doppler package; installing via brew under a non-default prefix; PATH customized in .zshrc but kamal runs from cron/systemd/CI where that rc is not sourced.

Related errors

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