basecamp/kamal · error · Kamal::ConfigurationError

Current version is #{Kamal::VERSION}, minimum required is #{

Error message

Current version is #{Kamal::VERSION}, minimum required is #{minimum_version}

What it means

Kamal::Configuration#ensure_valid_kamal_version compares the config's `minimum_version:` against the running Kamal::VERSION using Gem::Version semantics, and raises if the installed gem is older than the declared minimum. Config authors set minimum_version to assert that the deploy environment's kamal CLI is new enough for the config's features, so a mismatch means the CLI must be upgraded (or the floor lowered).

Source

Thrown at lib/kamal/configuration.rb:371

            if role.hosts.empty?
              raise Kamal::ConfigurationError, "No servers specified for the #{role.name} role. You can ignore this with allow_empty_roles: true"
            end
          end
        end
      end

      true
    end

    def ensure_valid_service_name
      raise Kamal::ConfigurationError, "Service name can only include alphanumeric characters, hyphens, and underscores" unless raw_config[:service] =~ /^[a-z0-9_-]+$/i

      true
    end

    def ensure_valid_kamal_version
      if minimum_version && Gem::Version.new(minimum_version) > Gem::Version.new(Kamal::VERSION)
        raise Kamal::ConfigurationError, "Current version is #{Kamal::VERSION}, minimum required is #{minimum_version}"
      end

      true
    end

    def ensure_retain_containers_valid
      raise Kamal::ConfigurationError, "Must retain at least 1 container" if retain_containers < 1

      true
    end

    def ensure_no_traefik_reboot_hooks
      hooks = %w[ pre-traefik-reboot post-traefik-reboot ].select { |hook_file| File.exist?(File.join(hooks_path, hook_file)) }

      if hooks.any?
        raise Kamal::ConfigurationError, "Found #{hooks.join(", ")}, these should be renamed to (pre|post)-proxy-reboot"
      end

View on GitHub (pinned to eee0083b38)

Solutions

1. Upgrade the kamal gem on the deploying machine: `gem install kamal` (or `bundle update kamal`), then confirm with `kamal version`.
2. If CI is the offender, bump the kamal version in the CI image or the Gemfile CI uses.
3. Only if you know the config does not actually need newer features, lower or remove `minimum_version:` — the safer fix is upgrading.

Example fix

# shell — before
$ kamal deploy
Current version is 2.1.3, minimum required is 2.3.0

# after
$ gem install kamal
$ kamal version
2.3.0
$ kamal deploy

require "kamal/version"

def kamal_new_enough?(required)
  Gem::Version.new(Kamal::VERSION) >= Gem::Version.new(required)
end

begin
  Kamal::Configuration.new(create_config_files: false)
rescue Kamal::ConfigurationError => e
  if e.message.include?("minimum required")
    abort "Run: gem install kamal (#{e.message})"
  end
  raise
end

When it happens

Trigger: `minimum_version: 2.3.0` in config/deploy.yml while `kamal version` reports 2.1.3; a teammate or CI image with an older gem running `kamal deploy`; upgrading the config to use new features and adding a minimum_version, then deploying from a machine that has not re-bundled.

Common situations: Mixed-version teams after one person adopts new config syntax; CI pipelines pinning an old kamal gem; `gem install kamal` vs Gemfile-managed kamal drifting apart.

Related errors

• You must specify a destination
• Missing required configuration for #{key}
• Missing required configuration for image
• No servers or accessories specified
• The primary_role #{primary_role_name} isn't defined

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