{"record":{"id":"b78efbdffb3648dd","repo":"puppetlabs/puppet","slug":"invalid-run-mode-mode","errorCode":null,"errorMessage":"Invalid run mode '#{mode}'","messagePattern":"Invalid run mode '#(.+?)'","errorType":"validation","errorClass":"Puppet::Settings::ValidationError","httpStatus":null,"severity":"error","filePath":"lib/puppet/settings.rb","lineNumber":588,"sourceCode":"\n  def print_configs?\n    (value(:configprint) != \"\" || value(:genconfig) || value(:genmanifest)) && true\n  end\n\n  # The currently configured run mode that is preferred for constructing the application configuration.\n  def preferred_run_mode\n    @preferred_run_mode_name || :user\n  end\n\n  # PRIVATE!  This only exists because we need a hook to validate the run mode when it's being set, and\n  #  it should never, ever, ever, ever be called from outside of this file.\n  # This method is also called when --run_mode MODE is used on the command line to set the default\n  #\n  # @param mode [String|Symbol] the name of the mode to have in effect\n  # @api private\n  def preferred_run_mode=(mode)\n    mode = mode.to_s.downcase.intern\n    raise ValidationError, \"Invalid run mode '#{mode}'\" unless [:server, :master, :agent, :user].include?(mode)\n\n    @preferred_run_mode_name = mode\n    # Changing the run mode has far-reaching consequences. Flush any cached\n    # settings so they will be re-generated.\n    flush_cache\n  end\n\n  def parse_config(text, file = \"text\")\n    begin\n      data = @config_file_parser.parse_file(file, text, ALLOWED_SECTION_NAMES)\n    rescue => detail\n      Puppet.log_exception(detail, \"Could not parse #{file}: #{detail}\")\n      return\n    end\n\n    # If we get here and don't have any data, we just return and don't muck with the current state of the world.\n    return if data.nil?\n","sourceCodeStart":570,"sourceCodeEnd":606,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/settings.rb#L570-L606","documentation":"Puppet::Settings#preferred_run_mode= normalizes the input (downcase, intern) and rejects anything outside [:server, :master, :agent, :user] with a Settings::ValidationError. The setter is the validation hook used for the --run_mode command-line flag and programmatic overrides; on success it flushes the settings cache because the run mode selects which config section applies.","triggerScenarios":"Passing `puppet agent --run_mode production` (run mode confused with environment); `--run_mode master` is accepted but `--run_mode puppetserver`, `--run_mode app` are not; calling Puppet.settings.preferred_run_mode = 'agentd' from wrapper code; harnesses forwarding arbitrary CLI flags into run_mode.","commonSituations":"Users conflating run_mode with environment or with the puppetserver service name; old blog posts suggesting custom run modes; CI wrappers constructing command lines dynamically.","solutions":["Use one of the four valid values: server, master (legacy alias of server), agent, user.","If you meant to select an environment, use `--environment <name>` instead of --run_mode.","Fix wrapper scripts that pass service names or environment names into --run_mode."],"exampleFix":"# before\npuppet agent --run_mode production --test\n\n# after\npuppet agent --environment production --test","handlingStrategy":"validation","validationCode":"mode = mode.to_s.downcase.to_sym\nunless %i[server master agent user].include?(mode)\n  raise ArgumentError, \"run_mode must be one of server/master/agent/user (got #{mode}); did you mean --environment?\"\nend\nPuppet.settings.preferred_run_mode = mode","typeGuard":"valid_run_mode = ->(m) { %i[server master agent user].include?(m.to_s.downcase.to_sym) }","tryCatchPattern":"begin\n  Puppet.settings.preferred_run_mode = requested\nrescue Puppet::Settings::ValidationError => e\n  Puppet.err(\"#{e.message}; valid: server, master, agent, user\")\n  exit 1\nend","preventionTips":["Do not pass environments or service names to --run_mode","Construct CLI invocations from a whitelist of flags in wrapper scripts","Remember `master` still works but is legacy — prefer `server`"],"tags":["puppet","settings","run-mode","cli","validation-error"],"backgroundTag":"invalid-enum-config-value","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}