basecamp/kamal · critical · Kamal::Cli::BootError

Failed to get endpoint for #{role} on #{host}, did the conta

Error message

Failed to get endpoint for #{role} on #{host}, did the container boot?

What it means

`kamal app start` starts existing app containers. When a role is configured with proxy: true (e.g. running Kamal's own proxy bundled in the app container), Kamal must re-point the proxy at the freshly started container: it captures the currently running version, then looks up the container id for that version with `docker ps -q`. If that lookup comes back empty, the container is not actually running, so there is no endpoint to deploy traffic to and Kamal raises Kamal::Cli::BootError.

Source

Thrown at lib/kamal/cli/app.rb:54

          execute *KAMAL.auditor.record("Tagging #{KAMAL.config.absolute_image} as the latest image"), verbosity: :debug
          execute *KAMAL.app.tag_latest_image
        end
      end
    end
  end

  desc "start", "Start existing app container on servers"
  def start
    modify(lock: true) do
      on_roles(KAMAL.roles, hosts: KAMAL.app_hosts, parallel: KAMAL.config.boot.parallel_roles) do |host, role|
        app = KAMAL.app(role: role, host: host)
        execute *KAMAL.auditor.record("Started app version #{KAMAL.config.version}"), verbosity: :debug
        execute *app.start, raise_on_non_zero_exit: false

        if role.running_proxy?
          version = capture_with_info(*app.current_running_version, raise_on_non_zero_exit: false).strip
          endpoint = capture_with_info(*app.container_id_for_version(version)).strip
          raise Kamal::Cli::BootError, "Failed to get endpoint for #{role} on #{host}, did the container boot?" if endpoint.empty?

          execute *app.deploy(target: endpoint)
        end
      end
    end
  end

  desc "stop", "Stop app container on servers"
  def stop
    modify(lock: true) do
      on_roles(KAMAL.roles, hosts: KAMAL.app_hosts, parallel: KAMAL.config.boot.parallel_roles) do |host, role|
        app = KAMAL.app(role: role, host: host)
        execute *KAMAL.auditor.record("Stopped app", role: role), verbosity: :debug

        if role.running_proxy?
          version = capture_with_info(*app.current_running_version, raise_on_non_zero_exit: false).strip
          endpoint = capture_with_info(*app.container_id_for_version(version)).strip
          if endpoint.present?

View on GitHub (pinned to eee0083b38)

Solutions

1. Inspect why the container is not running on the failing host: `kamal app logs -h <host>` (or ssh in and `docker ps -a`, `docker logs <container>`).
2. Fix the root cause (missing secrets/env, bad image tag, crashed entrypoint), then re-run `kamal app start`.
3. If the image/container was removed, run a full `kamal deploy` (or `kamal app boot`) instead of start, since start only starts an existing container.
4. Verify the role's proxy/labels config matches a container that exposes the expected endpoint.

Example fix

# before
kamal app start   # -> Failed to get endpoint for web on 1.2.3.4, did the container boot?
# after: find and fix the crashed container first
kamal app logs -h 1.2.3.4
kamal deploy      # boots a fresh version instead of starting a dead one

# Before `kamal app start`, confirm a container exists for the role on each host:
# `kamal app details` shows versions; or per host:
# ssh <host> docker ps -a --filter name=<service>-<role> --format '{{.Names}} {{.Status}}'
# Only run `app start` when a stopped container is present.

def container_present?(service, role, host)
  out = `ssh #{host} docker ps -aq --filter name=#{service}-#{role}`
  !out.strip.empty?
end

begin
  Kamal::CLI::App.new.start
rescue Kamal::Cli::BootError => e
  warn "app did not come up: #{e.message}"
  `kamal app logs`  # capture diagnostics before re-raising
  raise
end

When it happens

Trigger: `kamal app start` (or `kamal redeploy`/`kamal deploy` reaching the start step) on a role with running_proxy? true, where `app.start` did not result in a running container: crashed image, missing env/secrets, wrong port, or the container exits immediately after starting. The error fires on the host/role named in the message.

Common situations: App container crash-loops after a host reboot or docker restart because the image was pruned; role-level env or secrets file missing so entrypoint fails; version captured via container_id_for_version returns nothing because the old container was already removed; mixing kamal proxy roles with manually managed containers.

Related errors

• Failed to get endpoint for #{role} on #{host}, did the conta
• container not ready after #{KAMAL.config.deploy_timeout} sec
• Invalid publish IP address: #{ip}
• Hook `#{hook}` failed:\n#{e.message}
• Docker is not installed locally

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