basecamp/kamal · error · Kamal::ConfigurationError

Found #{hooks.join(", ")}, these should be renamed to (pre|p

Error message

Found #{hooks.join(", ")}, these should be renamed to (pre|post)-proxy-reboot

What it means

Kamal::Configuration#ensure_no_traefik_reboot_hooks scans the hooks directory (.kamal/hooks by default) for the legacy filenames `pre-traefik-reboot` and `post-traefik-reboot`. Kamal generalized Traefik into a generic proxy, so those hooks became `pre-proxy-reboot`/`post-proxy-reboot`; leaving old-named files raises this error listing the offending filenames so the rename is not silently skipped.

Source

Thrown at lib/kamal/configuration.rb:387

    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

      true
    end

    def ensure_one_host_for_ssl_roles
      roles.each(&:ensure_one_host_for_ssl)

      true
    end

    def ensure_unique_hosts_for_ssl_roles
      hosts = roles.select(&:ssl?).flat_map { |role| role.proxy.hosts }
      duplicates = hosts.tally.filter_map { |host, count| host if count > 1 }

      raise Kamal::ConfigurationError, "Different roles can't share the same host for SSL: #{duplicates.join(", ")}" if duplicates.any?

      true

View on GitHub (pinned to eee0083b38)

Solutions

1. Rename the files: `git mv .kamal/hooks/pre-traefik-reboot .kamal/hooks/pre-proxy-reboot` (and likewise post-).
2. Review the renamed hook's contents — proxy reboot hooks may need updated commands if they referenced traefik-specific behavior.
3. Commit the rename so teammates and CI do not hit the same error.

Example fix

# shell — before
.kamal/hooks/pre-traefik-reboot   # triggers error
.kamal/hooks/post-traefik-reboot

# after
mv .kamal/hooks/pre-traefik-reboot .kamal/hooks/pre-proxy-reboot
mv .kamal/hooks/post-traefik-reboot .kamal/hooks/post-proxy-reboot

LEGACY = %w[pre-traefik-reboot post-traefik-reboot]

def no_legacy_hooks?(hooks_dir = ".kamal/hooks")
  LEGACY.none? { |f| File.exist?(File.join(hooks_dir, f)) }
end

begin
  config = Kamal::Configuration.new(create_config_files: false)
rescue Kamal::ConfigurationError => e
  puts "Deploy config invalid: #{e.message}"
  exit 1
end

When it happens

Trigger: Upgrading a project from an older Kamal that had custom .kamal/hooks/pre-traefik-reboot or post-traefik-reboot scripts without renaming them; restoring a hooks directory from an old backup or template repo.

Common situations: Post-upgrade breakage after `bundle update kamal`; copying hooks from an old project; discovering the rename only at deploy time because hook files are not covered by config diffs.

Related errors

• Hook `#{hook}` failed:\n#{e.message}
• Failed to get endpoint for #{role} on #{host}, did the conta
• Failed to get endpoint for #{role} on #{host}, did the conta
• Unknown boot_config subcommand #{subcommand}
• Different roles can't share the same host for SSL: #{duplica

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