basecamp/kamal · error · RuntimeError

Missing required option '--account'

Error message

Missing required option '--account'

What it means

Adapters inheriting Kamal::Secrets::Adapters::Base default to requires_account? true (one_password, last_pass, bitwarden, etc.); Base#fetch raises RuntimeError when account is blank for those. Via the kamal CLI you normally hit the friendlier early return "No value provided for required options '--account'" (cli/secrets.rb:10) — this RuntimeError surfaces when calling the adapter programmatically or through other entry points that skip the CLI check.

Source

Thrown at lib/kamal/secrets/adapters/base.rb:5

class Kamal::Secrets::Adapters::Base
  delegate :optionize, to: Kamal::Utils

  def fetch(secrets, account: nil, from: nil)
    raise RuntimeError, "Missing required option '--account'" if requires_account? && account.blank?

    check_dependencies!

    session = login(account)
    fetch_secrets(secrets, from: from, account: account, session: session)
  end

  def requires_account?
    true
  end

  private
    def login(...)
      raise NotImplementedError
    end

    def fetch_secrets(...)
      raise NotImplementedError

View on GitHub (pinned to eee0083b38)

Solutions

1. Pass the account identifier: kamal secrets fetch -a one_password --account me@example.com KEY, or account: "me@example.com" in the Ruby API
2. For programmatic use, check adapter.requires_account? before calling fetch and supply account: accordingly
3. Switch to an adapter that does not need an account (bitwarden-sm, gcp_secret_manager, doppler) if that fits your vault

Example fix

# before
Kamal::Secrets::Adapters.lookup("one_password").fetch(["RAILS_MASTER_KEY"])
# => RuntimeError: Missing required option '--account'

# after
adapter = Kamal::Secrets::Adapters.lookup("one_password")
adapter.fetch(["RAILS_MASTER_KEY"], account: "me@example.com")

adapter = Kamal::Secrets::Adapters.lookup("one_password")
raise ArgumentError, "this adapter needs an account" if adapter.requires_account? && account.to_s.blank?

def fetch_with_account!(adapter, names, account: nil)
  raise ArgumentError, "#{adapter.class} requires an account" if adapter.requires_account? && account.blank?
  adapter.fetch(names, account: account)
end

begin
  adapter.fetch(names, account: account)
rescue RuntimeError => e
  retry if e.message.include?("Missing required option '--account'") && (account = prompt_for_account)
  raise
end

When it happens

Trigger: Calling Kamal::Secrets::Adapters.lookup("one_password").fetch(["KEY"]) with no account: kwarg; kamal secrets fetch -a one_password with no --account on a version/path that bypasses the CLI pre-check; passing --account "" (blank string).

Common situations: Scripts or rake tasks invoking the adapter API directly; forgetting --account for 1Password/LastPass/Bitwarden while gcp/doppler/bitwarden-sm need none; confusion over which adapters need an account.

Related errors

• Unknown secrets adapter: #{name}
• You must specify what to retrieve from Bitwarden Secrets Man
• No command provided. You must specify a command to execute.
• Could not read #{secrets} from AWS Secrets Manager
• Failed to login to and unlock Bitwarden

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