basecamp/kamal · error · ArgumentError

Invalid builder configuration: the `docker` driver does not

Error message

Invalid builder configuration: the `docker` driver does not not support multiple arches

What it means

Kamal::Configuration::Builder#valid? rejects `driver: docker` when arches.many? — i.e. more than one target architecture (e.g. [amd64, arm64]) is requested. Multi-arch builds require buildx with the docker-container driver and emulation; the plain docker driver can only build the host's native architecture, so Kamal raises this ArgumentError immediately.

Source

Thrown at lib/kamal/configuration/builder.rb:164

  def build_directory
    @build_directory ||=
      if git_clone?
        File.join clone_directory, repo_basename, repo_relative_pwd
      else
        "."
      end
  end

  def docker_driver?
    driver == "docker"
  end

  private
    def valid?
      if docker_driver?
        raise ArgumentError, "Invalid builder configuration: the `docker` driver does not not support remote builders" if remote
        raise ArgumentError, "Invalid builder configuration: the `docker` driver does not not support caching" if cached?
        raise ArgumentError, "Invalid builder configuration: the `docker` driver does not not support multiple arches" if arches.many?
      end

      if @options["cache"] && @options["cache"]["type"]
        raise ArgumentError, "Invalid cache type: #{@options["cache"]["type"]}" unless [ "gha", "registry" ].include?(@options["cache"]["type"])
      end
    end

    def cache_image
      builder_config["cache"]&.fetch("image", nil) || "#{image}-build-cache"
    end

    def cache_image_ref
      [ server, cache_image ].compact.join("/")
    end

    def cache_options
      builder_config["cache"]&.fetch("options", nil)
    end

View on GitHub (pinned to eee0083b38)

Solutions

Drop `driver: docker` so the default buildx/docker-container driver performs the multi-arch build.
Or restrict `arches:` to a single entry (the native arch) if you truly only target one platform.
Run `docker buildx ls` to confirm a builder with multi-arch capability exists after switching drivers.

Example fix

# config/deploy.yml — before
builder:
  driver: docker
  arches: [ amd64, arm64 ]

# after
builder:
  arches: [ amd64, arm64 ]

Defensive patterns

Strategy: validation

Validate before calling

def builder_driver_arches_compatible?(raw)
  b = raw["builder"] || {}
  !(b["driver"] == "docker" && Array(b["arches"]).size > 1)
end

Try / catch

begin
  Kamal::Configuration.new(create_config_files: false)
rescue ArgumentError, Kamal::ConfigurationError => e
  abort "#{e.message} — multi-arch needs buildx"
end

Prevention

Derive arches from your actual server fleet and re-check whenever hosts change architecture.
Run `docker buildx ls` to verify a multi-arch-capable builder.
Drop driver: docker before adding arm64 targets.

When it happens

Trigger: `builder: { driver: docker, arches: [ amd64, arm64 ] }` in config/deploy.yml; adding arm64 support (e.g. deploying to ARM VPS like Graviton or Raspberry Pi hosts) without removing a previously-set `driver: docker`; arch lists derived from servers that grew an ARM host.

Common situations: Fleet growth into mixed-architecture hosts; copying multi-arch examples from docs while a custom docker driver was set for speed; environment overrides appending arches to a base config pinned to driver docker.

Related errors

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