{"record":{"id":"2c6132163b388491","repo":"basecamp/kamal","slug":"current-version-is-kamal-version-minimum-requ","errorCode":null,"errorMessage":"Current version is #{Kamal::VERSION}, minimum required is #{minimum_version}","messagePattern":"Current version is #(.+?), minimum required is #(.+?)","errorType":"validation","errorClass":"Kamal::ConfigurationError","httpStatus":null,"severity":"error","filePath":"lib/kamal/configuration.rb","lineNumber":371,"sourceCode":"            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\n        end\n      end\n\n      true\n    end\n\n    def ensure_valid_service_name\n      raise Kamal::ConfigurationError, \"Service name can only include alphanumeric characters, hyphens, and underscores\" unless raw_config[:service] =~ /^[a-z0-9_-]+$/i\n\n      true\n    end\n\n    def ensure_valid_kamal_version\n      if minimum_version && Gem::Version.new(minimum_version) > Gem::Version.new(Kamal::VERSION)\n        raise Kamal::ConfigurationError, \"Current version is #{Kamal::VERSION}, minimum required is #{minimum_version}\"\n      end\n\n      true\n    end\n\n    def ensure_retain_containers_valid\n      raise Kamal::ConfigurationError, \"Must retain at least 1 container\" if retain_containers < 1\n\n      true\n    end\n\n    def ensure_no_traefik_reboot_hooks\n      hooks = %w[ pre-traefik-reboot post-traefik-reboot ].select { |hook_file| File.exist?(File.join(hooks_path, hook_file)) }\n\n      if hooks.any?\n        raise Kamal::ConfigurationError, \"Found #{hooks.join(\", \")}, these should be renamed to (pre|post)-proxy-reboot\"\n      end\n","sourceCodeStart":353,"sourceCodeEnd":389,"githubUrl":"https://github.com/basecamp/kamal/blob/eee0083b38661c3707c6b6052cc89e85038a096c/lib/kamal/configuration.rb#L353-L389","documentation":"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).","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Upgrade the kamal gem on the deploying machine: `gem install kamal` (or `bundle update kamal`), then confirm with `kamal version`.","If CI is the offender, bump the kamal version in the CI image or the Gemfile CI uses.","Only if you know the config does not actually need newer features, lower or remove `minimum_version:` — the safer fix is upgrading."],"exampleFix":"# shell — before\n$ kamal deploy\nCurrent version is 2.1.3, minimum required is 2.3.0\n\n# after\n$ gem install kamal\n$ kamal version\n2.3.0\n$ kamal deploy","handlingStrategy":"validation","validationCode":"require \"kamal/version\"\n\ndef kamal_new_enough?(required)\n  Gem::Version.new(Kamal::VERSION) >= Gem::Version.new(required)\nend","typeGuard":null,"tryCatchPattern":"begin\n  Kamal::Configuration.new(create_config_files: false)\nrescue Kamal::ConfigurationError => e\n  if e.message.include?(\"minimum required\")\n    abort \"Run: gem install kamal (#{e.message})\"\n  end\n  raise\nend","preventionTips":["Pin kamal in the project Gemfile so every machine and CI uses one version.","Add `kamal version` to CI before deploy jobs.","After bumping minimum_version in config, update the Gemfile/CI image in the same commit."],"tags":["kamal","version","configuration","toolchain"],"backgroundTag":"version-too-old","analyzedSha":"eee0083b38661c3707c6b6052cc89e85038a096c","analyzedAt":"2026-08-21T15:17:22.045Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}