{"record":{"id":"101fb78c179d7506","repo":"basecamp/kamal","slug":"invalid-cache-type-options-cache-type","errorCode":null,"errorMessage":"Invalid cache type: #{@options[\"cache\"][\"type\"]}","messagePattern":"Invalid cache type: #(.+?)","errorType":"exception","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/kamal/configuration/builder.rb","lineNumber":168,"sourceCode":"      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\n\n    def cache_from_config_for_gha\n      individual_options = cache_options&.split(\",\") || []\n      allowed_options = individual_options.select { |option| option =~ /^(url|url_v2|token|scope|timeout)=/ }","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/basecamp/kamal/blob/eee0083b38661c3707c6b6052cc89e85038a096c/lib/kamal/configuration/builder.rb#L150-L186","documentation":"Kamal::Configuration::Builder#valid? checks that when a cache type is configured (`builder.cache.type` present), it is one of exactly \"gha\" (GitHub Actions cache) or \"registry\" (cache image in the container registry). Any other string raises this ArgumentError with the offending value, since Kamal only knows how to wire those two buildx cache backends.","triggerScenarios":"`builder: { cache: { type: local } }` or `type: s3` in config/deploy.yml; typos like a trailing space, `GHA`, or `Registry` (the check is case-sensitive); ENV-sourced cache types such as `<%= ENV[\"CACHE_TYPE\"] %>` resolving to something unsupported.","commonSituations":"Copy-pasting buildx CLI cache type names that kamal does not expose; case mismatches from environment variables; stale docs or invented values in shared config templates.","solutions":["Set `cache.type` to `gha` or `registry` exactly (lowercase).","Choose gha when deploying from GitHub Actions; registry when an ordinary registry-backed cache fits all environments.","If the value is ENV-driven, whitelist it: `<%= %w[gha registry].include?(ENV[\"CACHE_TYPE\"]) ? ENV[\"CACHE_TYPE\"] : \"registry\" %>`."],"exampleFix":"# config/deploy.yml — before\nbuilder:\n  cache:\n    type: s3\n\n# after\nbuilder:\n  cache:\n    type: gha","handlingStrategy":"validation","validationCode":"CACHE_TYPES = %w[gha registry].freeze\n\ndef valid_cache_type?(raw)\n  type = raw.dig(\"builder\", \"cache\", \"type\")\n  type.nil? || CACHE_TYPES.include?(type)\nend","typeGuard":"def kamal_cache_type?(value)\n  %w[gha registry].include?(value.to_s)\nend","tryCatchPattern":"begin\n  Kamal::Configuration.new(create_config_files: false)\nrescue ArgumentError, Kamal::ConfigurationError => e\n  abort \"#{e.message} — cache type must be gha or registry\"\nend","preventionTips":["Use gha only in GitHub Actions pipelines; registry elsewhere.","Whitelist ENV-driven cache types in ERB templates.","Re-check allowed values after kamal upgrades — the list lives in Kamal::Configuration::Builder#valid?."],"tags":["kamal","builder","cache","validation","configuration"],"backgroundTag":"invalid-enum-value","analyzedSha":"eee0083b38661c3707c6b6052cc89e85038a096c","analyzedAt":"2026-08-21T15:17:22.045Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}