{"record":{"id":"4793e25a4424eb30","repo":"basecamp/kamal","slug":"you-must-specify-a-destination","errorCode":null,"errorMessage":"You must specify a destination","messagePattern":"You must specify a destination","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/kamal/configuration.rb","lineNumber":327,"sourceCode":"      primary_host: primary_host,\n      version: version,\n      repository: repository,\n      absolute_image: absolute_image,\n      service_with_version: service_with_version,\n      volume_args: volume_args,\n      ssh_options: ssh.to_h,\n      sshkit: sshkit.to_h,\n      builder: builder.to_h,\n      accessories: raw_config.accessories,\n      logging: logging_args\n    }.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","sourceCodeStart":309,"sourceCodeEnd":345,"githubUrl":"https://github.com/basecamp/kamal/blob/eee0083b38661c3707c6b6052cc89e85038a096c/lib/kamal/configuration.rb#L309-L345","documentation":"Kamal configurations can declare require_destination: true (read via raw_config.require_destination in Kamal::Configuration#require_destination?), which forces every invocation to pick a named destination — a config/deploy.<destination>.yml overlay on top of config/deploy.yml. During configuration load, if require_destination? is true but no destination was given (-d/--destination or KAMAL_DESTINATION), Kamal raises ArgumentError ('You must specify a destination') before any command runs.","triggerScenarios":"A multi-environment setup (config/deploy.production.yml, config/deploy.staging.yml) with require_destination: true in deploy.yml, then running `kamal deploy` or `kamal setup` without -d production. The error is raised by ensure_destination_if_required during Configuration initialization, affecting every CLI command that loads config.","commonSituations":"Adopting the destination workflow to prevent accidental production deploys from unparameterized commands; CI pipelines not yet updated to pass -d; locally habituated `kamal deploy` after require_destination: true was added by a teammate; KAMAL_DESTINATION env var unset in the deploy job.","solutions":["Pass the destination explicitly: `kamal deploy -d production` (or set KAMAL_DESTINATION=production for scripts).","If the guard is unwanted, remove require_destination: true from config/deploy.yml.","Make CI/deploy scripts destination-aware by default (export KAMAL_DESTINATION or add -d) so bare commands cannot fail or, worse, hit the wrong environment.","Verify the overlay file exists: config/deploy.<destination>.yml for the name you pass."],"exampleFix":"# before\nkamal deploy   # ArgumentError: You must specify a destination\n# after\nkamal deploy -d production\n# or in CI:\nexport KAMAL_DESTINATION=production\nkamal deploy","handlingStrategy":"validation","validationCode":"require \"yaml\"\nrequires_dest = YAML.load_file(\"config/deploy.yml\")[\"require_destination\"]\nabort \"this config requires -d <destination>\" if requires_dest && ENV[\"KAMAL_DESTINATION\"].to_s.empty?\nsystem(\"kamal deploy #{ENV[\"KAMAL_DESTINATION\"] ? \"-d #{ENV[\"KAMAL_DESTINATION\"]}\" : \"\"}\")","typeGuard":"def destination_satisfied?(config_hash, destination)\n  !config_hash[\"require_destination\"] || !destination.to_s.strip.empty?\nend","tryCatchPattern":"begin\n  Kamal::Configuration.new(create: nil, destination: ENV[\"DEST\"])\nrescue ArgumentError => e\n  raise unless e.message.include?(\"destination\")\n  abort \"set DEST (or pass -d) — this config requires an explicit destination\"\nend","preventionTips":["Export KAMAL_DESTINATION in every deploy job once you enable require_destination.","Add -d to documented runbook commands the moment the flag becomes mandatory.","Name destination overlay files exactly deploy.<destination>.yml to avoid follow-on errors."],"tags":["kamal","configuration","destination","cli","multi-environment"],"backgroundTag":"missing-deploy-destination","analyzedSha":"eee0083b38661c3707c6b6052cc89e85038a096c","analyzedAt":"2026-08-21T15:17:22.045Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}