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

Invalid run mode '#{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.

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)

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 %{value}: must be 'true'/'false' or a
• Invalid value '%{value}' for boolean parameter: %{name}
• Invalid certificate revocation value %{value}: must be one o
• Invalid duration format '%{value}' for parameter: %{name}
• Error parsing arguments

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