{"record":{"id":"8fc02a0c3c982d3e","repo":"basecamp/kamal","slug":"invalid-builder-configuration-the-docker-driver-8fc02a","errorCode":null,"errorMessage":"Invalid builder configuration: the `docker` driver does not not support caching","messagePattern":"Invalid builder configuration: the `docker` driver does not not support caching","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/kamal/configuration/builder.rb","lineNumber":163,"sourceCode":"\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\n      builder_config[\"cache\"]&.fetch(\"options\", nil)","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/basecamp/kamal/blob/eee0083b38661c3707c6b6052cc89e85038a096c/lib/kamal/configuration/builder.rb#L145-L181","documentation":"Kamal::Configuration::Builder#valid? raises this ArgumentError when `driver: docker` is combined with caching (cached? true, i.e. a cache `type:` or `image:` configured under builder). Cache export/import is a buildx/docker-container feature; the plain docker driver builds directly in the daemon and cannot attach a cache backend, so the configuration is rejected up front.","triggerScenarios":"`builder: { driver: docker, cache: { type: gha } }` in config/deploy.yml; inheriting a cache block from a shared base config while an environment override switches the driver to docker; enabling caching for CI speed and later switching drivers without pruning cache keys.","commonSituations":"Layered kamal configs merging incompatible builder keys; performance tuning carried over from buildx setups; docs and tutorials mixing driver and cache examples.","solutions":["Remove the `cache:` block (or set no cache type) when using `driver: docker`.","Or keep caching and use the default buildx/docker-container driver, which supports `cache: { type: gha|registry }`.","Check the fully merged config with `kamal config` when base and environment overrides both touch builder."],"exampleFix":"# config/deploy.yml — before\nbuilder:\n  driver: docker\n  cache:\n    type: gha\n\n# after\nbuilder:\n  cache:\n    type: gha","handlingStrategy":"validation","validationCode":"def builder_driver_cache_compatible?(raw)\n  b = raw[\"builder\"] || {}\n  !(b[\"driver\"] == \"docker\" && (b.dig(\"cache\", \"type\") || b.dig(\"cache\", \"image\")))\nend","typeGuard":null,"tryCatchPattern":"begin\n  Kamal::Configuration.new(create_config_files: false)\nrescue ArgumentError, Kamal::ConfigurationError => e\n  abort \"#{e.message} — caching needs the buildx driver\"\nend","preventionTips":["Use cache blocks only with the default (buildx) driver.","When switching drivers, delete now-inapplicable keys rather than leaving them.","Centralize builder config in one file instead of merging partial builder blocks across overlays."],"tags":["kamal","builder","cache","docker","configuration"],"backgroundTag":"incompatible-config-combination","analyzedSha":"eee0083b38661c3707c6b6052cc89e85038a096c","analyzedAt":"2026-08-21T15:17:22.045Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}