basecamp/kamal · critical · Kamal::ConfigurationError

Missing required configuration for #{key}

Error message

Missing required configuration for #{key}

What it means

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.

Source

Thrown at lib/kamal/configuration.rb:335

      builder: builder.to_h,
      accessories: raw_config.accessories,
      logging: logging_args
    }.compact
  end

  private
    # Will raise ArgumentError if any required config keys are missing
    def ensure_destination_if_required
      if require_destination? && destination.nil?
        raise ArgumentError, "You must specify a destination"
      end

      true
    end

    def ensure_required_keys_present
      %i[ service registry ].each do |key|
        raise Kamal::ConfigurationError, "Missing required configuration for #{key}" unless raw_config[key].present?
      end

      raise Kamal::ConfigurationError, "Missing required configuration for image" if image.blank?

      if raw_config.servers.nil?
        raise Kamal::ConfigurationError, "No servers or accessories specified" unless raw_config.accessories.present?
      else
        unless role(primary_role_name).present?
          raise Kamal::ConfigurationError, "The primary_role #{primary_role_name} isn't defined"
        end

        if primary_role.hosts.empty?
          raise Kamal::ConfigurationError, "No servers specified for the #{primary_role.name} primary_role"
        end

        unless allow_empty_roles?
          roles.each do |role|
            if role.hosts.empty?

View on GitHub (pinned to eee0083b38)

Solutions

1. 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).
2. Check YAML indentation and exact key names (service, not services/app/name; registry, not registries/image).
3. If using destinations, ensure the overlay merges rather than blanks the key and that require_destination handling didn't skip loading the right file.
4. 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.

Example fix

# before (config/deploy.yml)
servers:
  web:
    hosts:
      - 203.0.113.10
# -> Missing required configuration for service (then registry)
# after
service: myapp
image: myuser/myapp
registry:
  username: myuser
  password:
    - KAMAL_REGISTRY_PASSWORD
servers:
  web:
    hosts:
      - 203.0.113.10

require "yaml"
config = YAML.load_file("config/deploy.yml") || {}
missing = %w[service registry].reject { |k| config[k] && !config[k].to_s.empty? }
abort "deploy.yml missing required keys: #{missing.join(', ')}" unless missing.empty?
system("kamal deploy")

def required_config_present?(config_hash)
  %i[service registry].all? { |k| config_hash[k].present? }
end

begin
  Kamal::Configuration.new(create: nil, destination: nil)
rescue Kamal::ConfigurationError => e
  raise unless e.message.include?("Missing required configuration")
  abort "fix config/deploy.yml: #{e.message}"
end

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• #{error_context}#{message}
• Service name can only include alphanumeric characters, hyphe
• Invalid hooks_output '#{level}'#{context}, must be one of: #
• Invalid cache type: #{@options["cache"]["type"]}
• You must specify a destination

AI-assisted analysis of basecamp/kamal@eee0083b38 (2026-08-21). Data as JSON: /api/errors/d21ee9d5ec41b8d0. Report an issue: GitHub.