puppetlabs/puppet · error · Puppet::Settings::ValidationError

Invalid run mode '#

Error message

Invalid run mode '#{mode}'

What it means

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.

Solutions

1. Use one of the four valid values: server, master (legacy alias of server), agent, user.
2. If you meant to select an environment, use `--environment <name>` instead of --run_mode.
3. Fix wrapper scripts that pass service names or environment names into --run_mode.

Example fix

# before
puppet agent --run_mode production --test

# after
puppet agent --environment production --test

mode = mode.to_s.downcase.to_sym
unless %i[server master agent user].include?(mode)
  raise ArgumentError, "run_mode must be one of server/master/agent/user (got #{mode}); did you mean --environment?"
end
Puppet.settings.preferred_run_mode = mode

valid_run_mode = ->(m) { %i[server master agent user].include?(m.to_s.downcase.to_sym) }

begin
  Puppet.settings.preferred_run_mode = requested
rescue Puppet::Settings::ValidationError => e
  Puppet.err("#{e.message}; valid: server, master, agent, user")
  exit 1
end

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid autosign value
• Invalid certificate revocation value
• Invalid duration format
• Invalid value ' ' for boolean parameter
• a short option name can't be a number or a dash

AI-assisted analysis of puppetlabs/puppet@e227c27540 (2026-08-21). Data as JSON: /api/errors/b78efbdffb3648dd. Report an issue: GitHub.

Appendix: source

Thrown at lib/puppet/settings.rb:588

  def print_configs?
    (value(:configprint) != "" || value(:genconfig) || value(:genmanifest)) && true
  end

  # The currently configured run mode that is preferred for constructing the application configuration.
  def preferred_run_mode
    @preferred_run_mode_name || :user
  end

  # PRIVATE!  This only exists because we need a hook to validate the run mode when it's being set, and
  #  it should never, ever, ever, ever be called from outside of this file.
  # This method is also called when --run_mode MODE is used on the command line to set the default
  #
  # @param mode [String|Symbol] the name of the mode to have in effect
  # @api private
  def preferred_run_mode=(mode)
    mode = mode.to_s.downcase.intern
    raise ValidationError, "Invalid run mode '#{mode}'" unless [:server, :master, :agent, :user].include?(mode)

    @preferred_run_mode_name = mode
    # Changing the run mode has far-reaching consequences. Flush any cached
    # settings so they will be re-generated.
    flush_cache
  end

  def parse_config(text, file = "text")
    begin
      data = @config_file_parser.parse_file(file, text, ALLOWED_SECTION_NAMES)
    rescue => detail
      Puppet.log_exception(detail, "Could not parse #{file}: #{detail}")
      return
    end

    # If we get here and don't have any data, we just return and don't muck with the current state of the world.
    return if data.nil?

View on GitHub (pinned to e227c27540)