puppetlabs/puppet · error · ArgumentError

Global option %{option} does not exist in Puppet.settings

Error message

Global option %{option} does not exist in Puppet.settings

What it means

Puppet::Interface::OptionManager#display_global_options (Faces DSL, aliased as display_global_option) declares which Puppet settings surface as global options on a face. Every name must already exist in Puppet.settings — underscored setting symbols like :environment or :certname — or ArgumentError is raised at face-load time (lib/puppet/interface/option_manager.rb:15).

Source

Thrown at lib/puppet/interface/option_manager.rb:15

# frozen_string_literal: true

# This class is not actually public API, but the method
# {Puppet::Interface::OptionManager#option option} is public when used
# as part of the Faces DSL (i.e. from within a
# {Puppet::Interface.define define} block).
# @api public
module Puppet::Interface::OptionManager
  # @api private
  def display_global_options(*args)
    @display_global_options ||= []
    [args].flatten.each do |refopt|
      unless Puppet.settings.include?(refopt)
        # TRANSLATORS 'Puppet.settings' references to the Puppet settings options and should not be translated
        raise ArgumentError, _("Global option %{option} does not exist in Puppet.settings") % { option: refopt }
      end

      @display_global_options << refopt if refopt
    end
    @display_global_options.uniq!
    @display_global_options
  end
  alias :display_global_option :display_global_options

  def all_display_global_options
    walk_inheritance_tree(@display_global_options, :all_display_global_options)
  end

  # @api private
  def walk_inheritance_tree(start, sym)
    result = start || []
    if is_a?(Class) and superclass.respond_to?(sym)
      result = superclass.send(sym) + result

View on GitHub (pinned to e227c27540)

Solutions

1. Use underscore names exactly as Puppet defines them: `display_global_options 'environment', 'certname'`
2. Verify membership first: `Puppet.settings.include?(:log_level)`
3. List valid names via `puppet config print` (or inspect Puppet.settings) to confirm the exact spelling

Example fix

# before
display_global_options "log-level"

# after
display_global_options "log_level"

names = %w[environment certname]
unknown = names.reject { |n| Puppet.settings.include?(n) }
raise ArgumentError, "not Puppet settings: #{unknown.join(', ')}" unless unknown.empty?
display_global_options(*names)

When it happens

Trigger: `display_global_options 'environment', 'colour'` (typo); dasherized names like 'dns-alt-names' (settings are underscored: 'dns_alt_names'); referencing a setting renamed or removed in the Puppet version in use.

Common situations: Typos; porting a face to a newer Puppet where a setting was renamed; copying documentation that shows CLI-style dashed flags instead of setting names.

Related errors

• %{name} can't be optional and have a default value
• default value for %{name} is a %{class_name}, not a proc
• before action hook for %{name} is a %{class_name}, not a pro
• after action hook for %{name} is a %{class_name}, not a proc
• %{option} before_action requires a block

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