basecamp/kamal · error · RuntimeError

AWS CLI is not installed

Error message

AWS CLI is not installed

What it means

Before fetching, the AWS adapter's check_dependencies! runs `aws --version` and inspects $?. If the aws executable is missing from PATH (or not executable), Kamal raises RuntimeError "AWS CLI is not installed". Kamal never talks to AWS via the SDK here — the aws CLI is a hard requirement of this adapter.

Source

Thrown at lib/kamal/secrets/adapters/aws_secrets_manager.rb:52

      cmd = args.join(" ")

      `#{cmd}`.tap do |secrets|
        raise RuntimeError, "Could not read #{secrets} from AWS Secrets Manager" unless $?.success?

        secrets = JSON.parse(secrets)

        return secrets["SecretValues"] unless secrets["Errors"].present?

        raise RuntimeError, secrets["Errors"].map { |error| "#{error['SecretId']}: #{error['Message']}" }.join(" ")
      end
    end

    def stringify_secret_value(value)
      value.is_a?(String) ? value : JSON.dump(value)
    end

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

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

View on GitHub (pinned to eee0083b38)

Solutions

1. Install AWS CLI v2: brew install awscli (macOS), or follow AWS's official install instructions for Linux (curl the official bundle) — apt's awscli is often v1 and too old
2. Verify the check passes: aws --version in the same shell/environment kamal runs in
3. For CI/Docker, add the awscli installation step to the image or pipeline before calling kamal secrets fetch

Example fix

# before
$ kamal secrets fetch -a aws_secrets_manager RAILS_MASTER_KEY
# RuntimeError: AWS CLI is not installed

# fix (terminal)
brew install awscli
aws --version   # aws-cli/2.x.x
kamal secrets fetch -a aws_secrets_manager RAILS_MASTER_KEY

abort "AWS CLI v2 not installed — install from https://docs.aws.amazon.com/cli/" unless system("aws --version > /dev/null 2>&1")

When it happens

Trigger: kamal secrets fetch -a aws_secrets_manager on a machine without the AWS CLI installed, with a broken PATH, in a minimal Docker/CI image lacking awscli, or where aws is an alias/function not visible to the subshell.

Common situations: Fresh macOS/Linux box; slim CI containers (alpine images without awscli); rbenv/other shims shadowing PATH so `aws` resolves nowhere; uninstalling awscli after switching profiles.

Related errors

• Could not read #{secrets} from AWS Secrets Manager
• Bitwarden CLI is not installed
• #{error['SecretId']}: #{error['Message']}
• Bitwarden Secrets Manager CLI is not installed
• Doppler CLI is not installed

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