{"record":{"id":"c1e771c4e615cfa3","repo":"basecamp/kamal","slug":"invalid-builder-configuration-the-docker-driver-c1e771","errorCode":null,"errorMessage":"Invalid builder configuration: the `docker` driver does not not support multiple arches","messagePattern":"Invalid builder configuration: the `docker` driver does not not support multiple arches","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/kamal/configuration/builder.rb","lineNumber":164,"sourceCode":"  def build_directory\n    @build_directory ||=\n      if git_clone?\n        File.join clone_directory, repo_basename, repo_relative_pwd\n      else\n        \".\"\n      end\n  end\n\n  def docker_driver?\n    driver == \"docker\"\n  end\n\n  private\n    def valid?\n      if docker_driver?\n        raise ArgumentError, \"Invalid builder configuration: the `docker` driver does not not support remote builders\" if remote\n        raise ArgumentError, \"Invalid builder configuration: the `docker` driver does not not support caching\" if cached?\n        raise ArgumentError, \"Invalid builder configuration: the `docker` driver does not not support multiple arches\" if arches.many?\n      end\n\n      if @options[\"cache\"] && @options[\"cache\"][\"type\"]\n        raise ArgumentError, \"Invalid cache type: #{@options[\"cache\"][\"type\"]}\" unless [ \"gha\", \"registry\" ].include?(@options[\"cache\"][\"type\"])\n      end\n    end\n\n    def cache_image\n      builder_config[\"cache\"]&.fetch(\"image\", nil) || \"#{image}-build-cache\"\n    end\n\n    def cache_image_ref\n      [ server, cache_image ].compact.join(\"/\")\n    end\n\n    def cache_options\n      builder_config[\"cache\"]&.fetch(\"options\", nil)\n    end","sourceCodeStart":146,"sourceCodeEnd":182,"githubUrl":"https://github.com/basecamp/kamal/blob/eee0083b38661c3707c6b6052cc89e85038a096c/lib/kamal/configuration/builder.rb#L146-L182","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","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."],"exampleFix":"# config/deploy.yml — before\nbuilder:\n  driver: docker\n  arches: [ amd64, arm64 ]\n\n# after\nbuilder:\n  arches: [ amd64, arm64 ]","handlingStrategy":"validation","validationCode":"def builder_driver_arches_compatible?(raw)\n  b = raw[\"builder\"] || {}\n  !(b[\"driver\"] == \"docker\" && Array(b[\"arches\"]).size > 1)\nend","typeGuard":null,"tryCatchPattern":"begin\n  Kamal::Configuration.new(create_config_files: false)\nrescue ArgumentError, Kamal::ConfigurationError => e\n  abort \"#{e.message} — multi-arch needs buildx\"\nend","preventionTips":["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."],"tags":["kamal","builder","multi-arch","docker","configuration"],"backgroundTag":"incompatible-config-combination","analyzedSha":"eee0083b38661c3707c6b6052cc89e85038a096c","analyzedAt":"2026-08-21T15:17:22.045Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}