{"record":{"id":"54892b969fa9ba86","repo":"basecamp/kamal","slug":"invalid-builder-configuration-the-docker-driver","errorCode":null,"errorMessage":"Invalid builder configuration: the `docker` driver does not not support remote builders","messagePattern":"Invalid builder configuration: the `docker` driver does not not support remote builders","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/kamal/configuration/builder.rb","lineNumber":162,"sourceCode":"  end\n\n  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","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/basecamp/kamal/blob/eee0083b38661c3707c6b6052cc89e85038a096c/lib/kamal/configuration/builder.rb#L144-L180","documentation":"Kamal::Configuration::Builder#valid? rejects combinations where `driver: docker` (the plain Docker builder rather than docker-container/buildx) is used together with `remote:`. The plain docker driver runs builds inside the local Docker daemon, so it cannot dispatch builds to a remote builder; Kamal raises this ArgumentError at configuration load to prevent a nonsensical build setup.","triggerScenarios":"`builder: { driver: docker, remote: ssh://user@buildhost }` in config/deploy.yml; keeping a remote: URL from a previous buildx setup after switching driver to docker; merging environment overrides that add remote while a base config pins driver: docker.","commonSituations":"Experimenting with the docker driver for speed (it avoids QEMU/build containers) while forgetting to strip remote builder config; layered configs (deploy.yml + deploy.production.yml) combining incompatible keys.","solutions":["Remove the `remote:` key when using `driver: docker` — builds will run in the local Docker daemon.","Or keep the remote builder but drop `driver: docker` so the default buildx/docker-container driver handles remote dispatch.","If layering configs, audit the merged result (`kamal config`) to confirm the driver/remote pair is intentional."],"exampleFix":"# config/deploy.yml — before\nbuilder:\n  driver: docker\n  remote: ssh://buildhost\n\n# after\nbuilder:\n  driver: docker","handlingStrategy":"validation","validationCode":"def builder_driver_remote_compatible?(raw)\n  b = raw[\"builder\"] || {}\n  !(b[\"driver\"] == \"docker\" && b[\"remote\"])\nend","typeGuard":"def docker_driver_config?(builder_cfg)\n  builder_cfg.is_a?(Hash) && builder_cfg[\"driver\"] == \"docker\" &&\n    !builder_cfg[\"remote\"] && !builder_cfg.dig(\"cache\", \"type\") &&\n    Array(builder_cfg[\"arches\"]).size <= 1\nend","tryCatchPattern":"begin\n  Kamal::Configuration.new(create_config_files: false)\nrescue ArgumentError, Kamal::ConfigurationError => e\n  abort \"#{e.message}\"\nend","preventionTips":["Never combine driver: docker with remote, cache, or multi-arch.","Review merged builder config (`kamal config`) when layering environment overlays.","Prefer omitting `driver` unless you specifically need the plain docker builder."],"tags":["kamal","builder","docker","configuration"],"backgroundTag":"incompatible-config-combination","analyzedSha":"eee0083b38661c3707c6b6052cc89e85038a096c","analyzedAt":"2026-08-21T15:17:22.045Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}