basecamp/kamal · error · ArgumentError

Unknown boot_config subcommand #{subcommand}

Error message

Unknown boot_config subcommand #{subcommand}

What it means

`kamal proxy boot_config SUBCOMMAND` manages boot-time proxy configuration (the customizations the proxy persists for kamal-managed options like logging or publish). The command dispatches on the subcommand string — 'show' (and its '?' alias) prints per-host boot config, 'reset' resets boot options/image/version/run-command — and any other first argument falls into the else branch and raises ArgumentError with the unknown subcommand name.

Source

Thrown at lib/kamal/cli/proxy.rb:102

        else
          execute *proxy.reset_run_command, raise_on_non_zero_exit: false
        end
      end
    when "get"

      on(KAMAL.proxy_hosts) do |host|
        puts "Host #{host}: #{capture_with_info(*KAMAL.proxy(host).boot_config)}"
      end
    when "reset"
      on(KAMAL.proxy_hosts) do |host|
        proxy = KAMAL.proxy(host)
        execute *proxy.reset_boot_options, raise_on_non_zero_exit: false
        execute *proxy.reset_image, raise_on_non_zero_exit: false
        execute *proxy.reset_image_version, raise_on_non_zero_exit: false
        execute *proxy.reset_run_command, raise_on_non_zero_exit: false
      end
    else
      raise ArgumentError, "Unknown boot_config subcommand #{subcommand}"
    end
  end

  desc "reboot", "Reboot proxy on servers (stop container, remove container, start new container)"
  option :rolling, type: :boolean, default: false, desc: "Reboot proxy on hosts in sequence, rather than in parallel"
  option :confirmed, aliases: "-y", type: :boolean, default: false, desc: "Proceed without confirmation question"
  def reboot
    confirming "This will cause a brief outage on each host. Are you sure?" do
      modify(lock: true) do
        host_groups = options[:rolling] ? KAMAL.proxy_hosts : [ KAMAL.proxy_hosts ]
        host_groups.each do |hosts|
          host_list = Array(hosts).join(",")
          run_hook "pre-proxy-reboot", hosts: host_list
          on(hosts) do |host|
            proxy = KAMAL.proxy(host)
            execute *KAMAL.auditor.record("Rebooted proxy"), verbosity: :debug
            execute *KAMAL.registry.login

View on GitHub (pinned to eee0083b38)

Solutions

  1. Use a supported subcommand: `kamal proxy boot_config show` (alias '?') to display, `kamal proxy boot_config reset` to reset.
  2. Run `kamal proxy boot_config --help` (or `kamal proxy --help`) to list the exact options accepted by your kamal version.
  3. Fix wrapper scripts to validate/whitelist the subcommand before invoking.

Example fix

# before
kamal proxy boot_config get
# after
kamal proxy boot_config show
# or reset when you want defaults back:
kamal proxy boot_config reset
Defensive patterns

Strategy: validation

Validate before calling

SUBCOMMANDS = %w[show ? reset].freeze
sub = ARGV.shift
abort "unknown boot_config subcommand '#{sub}'; use one of #{SUBCOMMANDS.join(', ')}" unless SUBCOMMANDS.include?(sub)
system("kamal proxy boot_config #{sub}")

Type guard

def valid_boot_config_subcommand?(sub)
  %w[show ? reset].include?(sub)
end

Try / catch

begin
  Kamal::CLI::Proxy.new.invoke(:boot_config, [ sub ])
rescue ArgumentError => e
  raise unless e.message.start_with?("Unknown boot_config")
  warn "valid subcommands: show (?), reset"
end

Prevention

When it happens

Trigger: Running `kamal proxy boot_config get`, `... config`, `... list`, or a typo like `... shoe`/`... reste`. Also invoked by wrapper scripts that pass an empty or wrong argument (e.g. `kamal proxy boot_config "$SUBCMD"` with SUBCMD unset → dispatches with nil/empty and hits the else).

Common situations: Guessing the subcommand name from other kamal commands ('get' vs 'show'); docs/tutorials referencing an older or newer subcommand set; scripts with a variable subcommand that can be empty in CI.

Related errors

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