{"record":{"id":"ae496df46a3b689b","repo":"basecamp/kamal","slug":"missing-required-configuration-for-image","errorCode":null,"errorMessage":"Missing required configuration for image","messagePattern":"Missing required configuration for image","errorType":"validation","errorClass":"Kamal::ConfigurationError","httpStatus":null,"severity":"error","filePath":"lib/kamal/configuration.rb","lineNumber":338,"sourceCode":"    }.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?\n              raise Kamal::ConfigurationError, \"No servers specified for the #{role.name} role. You can ignore this with allow_empty_roles: true\"\n            end\n          end","sourceCodeStart":320,"sourceCodeEnd":356,"githubUrl":"https://github.com/basecamp/kamal/blob/eee0083b38661c3707c6b6052cc89e85038a096c/lib/kamal/configuration.rb#L320-L356","documentation":"Kamal raises this Kamal::ConfigurationError while loading config/deploy.yml, in ensure_required_keys_present. After verifying that the required `service` and `registry` keys exist, it checks that an `image` is present, because Kamal needs the name of the Docker image to build, tag, and push to the registry. The image value comes from raw_config[:image], so a missing or blank value means deploys, builds, and pushes have no image reference to operate on.","triggerScenarios":"Running any Kamal command (e.g. `kamal deploy`, `kamal build`) with a config/deploy.yml that has no top-level `image:` key, an `image:` set to nil/empty string, or an ERB-templated `image: <%= ENV[\"IMAGE\"] %>` where the environment variable is unset so it renders blank.","commonSituations":"New Kamal setups copied from a tutorial that omits `image`; configs migrated from kamal 1.x where keys were reshuffled and `image` was dropped; ERB interpolation depending on an env var missing in CI; YAML indentation putting `image` under the wrong parent key.","solutions":["Add a top-level `image: your-app-name` key to config/deploy.yml (Kamal tags it as registry/.../image:version at push time).","If the value is ERB-interpolated, verify the referenced ENV var is set in every environment that runs kamal, CI shells included.","Check YAML indentation — `image` must be a sibling of `service` and `servers`, not nested under them.","If overriding config per environment (config/deploy.production.yml), confirm the merge still yields an `image`."],"exampleFix":"# config/deploy.yml — before\nservice: myapp\nregistry: registry.example.com\nservers:\n  web:\n    - 1.2.3.4\n\n# after\nservice: myapp\nimage: myapp\nregistry: registry.example.com\nservers:\n  web:\n    - 1.2.3.4","handlingStrategy":"validation","validationCode":"require \"yaml\"\nrequire \"erb\"\n\ndef config_ready_for_kamal?(path = \"config/deploy.yml\")\n  raw = YAML.safe_load(ERB.new(File.read(path)).result, aliases: true) || {}\n  %w[service registry].all? { |k| raw[k].to_s.strip != \"\" } && raw[\"image\"].to_s.strip != \"\"\nend","typeGuard":null,"tryCatchPattern":"begin\n  config = Kamal::Configuration.new(create_config_files: false)\nrescue Kamal::ConfigurationError => e\n  puts \"Deploy config invalid: #{e.message}\"\n  exit 1\nend","preventionTips":["Keep a CI step that runs `kamal config` (or loads Kamal::Configuration) on every config change.","Make ERB-interpolated values raise loudly when their ENV var is unset instead of rendering blank.","Use a config schema checklist (service, image, registry, servers) reviewed at project setup."],"tags":["kamal","configuration","deploy","required-field"],"backgroundTag":"missing-required-config-key","analyzedSha":"eee0083b38661c3707c6b6052cc89e85038a096c","analyzedAt":"2026-08-21T15:17:22.045Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}