{"record":{"id":"d21ee9d5ec41b8d0","repo":"basecamp/kamal","slug":"missing-required-configuration-for-key","errorCode":null,"errorMessage":"Missing required configuration for #{key}","messagePattern":"Missing required configuration for #(.+?)","errorType":"validation","errorClass":"Kamal::ConfigurationError","httpStatus":null,"severity":"critical","filePath":"lib/kamal/configuration.rb","lineNumber":335,"sourceCode":"      builder: builder.to_h,\n      accessories: raw_config.accessories,\n      logging: logging_args\n    }.compact\n  end\n\n  private\n    # Will raise ArgumentError if any required config keys are missing\n    def ensure_destination_if_required\n      if require_destination? && destination.nil?\n        raise ArgumentError, \"You must specify a destination\"\n      end\n\n      true\n    end\n\n    def ensure_required_keys_present\n      %i[ service registry ].each do |key|\n        raise Kamal::ConfigurationError, \"Missing required configuration for #{key}\" unless raw_config[key].present?\n      end\n\n      raise Kamal::ConfigurationError, \"Missing required configuration for image\" if image.blank?\n\n      if raw_config.servers.nil?\n        raise Kamal::ConfigurationError, \"No servers or accessories specified\" unless raw_config.accessories.present?\n      else\n        unless role(primary_role_name).present?\n          raise Kamal::ConfigurationError, \"The primary_role #{primary_role_name} isn't defined\"\n        end\n\n        if primary_role.hosts.empty?\n          raise Kamal::ConfigurationError, \"No servers specified for the #{primary_role.name} primary_role\"\n        end\n\n        unless allow_empty_roles?\n          roles.each do |role|\n            if role.hosts.empty?","sourceCodeStart":317,"sourceCodeEnd":353,"githubUrl":"https://github.com/basecamp/kamal/blob/eee0083b38661c3707c6b6052cc89e85038a096c/lib/kamal/configuration.rb#L317-L353","documentation":"Kamal::Configuration#ensure_required_keys_present validates the raw config hash (from config/deploy.yml + destination overlay) during initialization: for each key in [:service, :registry] it raises Kamal::ConfigurationError ('Missing required configuration for <key>') unless raw_config[key] is present. So a deploy.yml without a service: name or without a registry: section fails at config load time, before any host is contacted.","triggerScenarios":"Initial `kamal init`-generated or hand-written config/deploy.yml missing the top-level `service:` key or the `registry:` block (registry is required by this code path even though you may deploy without pushing); YAML indentation putting keys under the wrong parent; typos like `services:` or `registries:`; loading a config file with ERB that renders the key to nil/empty.","commonSituations":"First-time setup following an outdated tutorial where registry was optional; a destination overlay accidentally shadowing registry: with nil; converting from kamal 1.x config where the key layout differed; secrets/ERB template errors silently producing an empty value.","solutions":["Open config/deploy.yml and add the missing top-level key: `service: myapp` and a `registry:` block (e.g. registry: username: ... password: KAMAL_REGISTRY_PASSWORD or the server/port form).","Check YAML indentation and exact key names (service, not services/app/name; registry, not registries/image).","If using destinations, ensure the overlay merges rather than blanks the key and that require_destination handling didn't skip loading the right file.","Run a quick sanity check: `ruby -e \"require 'yaml'; c=YAML.load_file('config/deploy.yml'); p c.keys\"` to see what keys are actually present."],"exampleFix":"# before (config/deploy.yml)\nservers:\n  web:\n    hosts:\n      - 203.0.113.10\n# -> Missing required configuration for service (then registry)\n# after\nservice: myapp\nimage: myuser/myapp\nregistry:\n  username: myuser\n  password:\n    - KAMAL_REGISTRY_PASSWORD\nservers:\n  web:\n    hosts:\n      - 203.0.113.10","handlingStrategy":"validation","validationCode":"require \"yaml\"\nconfig = YAML.load_file(\"config/deploy.yml\") || {}\nmissing = %w[service registry].reject { |k| config[k] && !config[k].to_s.empty? }\nabort \"deploy.yml missing required keys: #{missing.join(', ')}\" unless missing.empty?\nsystem(\"kamal deploy\")","typeGuard":"def required_config_present?(config_hash)\n  %i[service registry].all? { |k| config_hash[k].present? }\nend","tryCatchPattern":"begin\n  Kamal::Configuration.new(create: nil, destination: nil)\nrescue Kamal::ConfigurationError => e\n  raise unless e.message.include?(\"Missing required configuration\")\n  abort \"fix config/deploy.yml: #{e.message}\"\nend","preventionTips":["Start from `kamal init`'s generated deploy.yml so required keys are present from day one.","Lint deploy.yml in CI (YAML parse + key presence) before any deploy job runs.","After refactoring config or adding ERB, re-check that service and registry still resolve to non-empty values."],"tags":["kamal","configuration","yaml","validation","setup"],"backgroundTag":"missing-config-key","analyzedSha":"eee0083b38661c3707c6b6052cc89e85038a096c","analyzedAt":"2026-08-21T15:17:22.045Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}