puppetlabs/puppet · error · CommandlineError

unknown argument '%{arg}'

Error message

unknown argument '%{arg}'

What it means

When a token has valid option syntax but resolves to no registered long or short name (including the '[no-]' registry), sym is nil; unless the parser was put into ignore_invalid_options mode (PuppetOptionParser uses that for its first global pass because the target application is not yet known), parse raises CommandlineError at trollop.rb:365. A legacy fallback once matched underscore/dash variants with only a deprecation warning, but that partial matching is deprecated, so misspelled long options now fail. Inside the puppet executable the raw error is wrapped as PuppetOptionError 'Error parsing arguments' by puppet_option_parser.rb:77-78.

Source

Thrown at lib/puppet/util/command_line/trollop.rb:365

                end
              when /^--([^-]\S*)$/
                possible_match = @long[::Regexp.last_match(1)] || @long["[no-]#{::Regexp.last_match(1)}"]
                if !possible_match
                  partial_match = @long[::Regexp.last_match(1).tr('-', '_')] || @long[::Regexp.last_match(1).tr('_', '-')] || @long["[no-]#{::Regexp.last_match(1).tr('-', '_')}"] || @long["[no-]#{::Regexp.last_match(1).tr('_', '-')}"]
                  if partial_match
                    Puppet.deprecation_warning _("Partial argument match detected: correct argument is %{partial_match}, got %{arg}. Partial argument matching is deprecated and will be removed in a future release.") % { arg: arg, partial_match: partial_match }
                  end
                  partial_match
                else
                  possible_match
                end
              else
                raise CommandlineError, _("invalid argument syntax: '%{arg}'") % { arg: arg }
              end

        unless sym
          next 0 if ignore_invalid_options
          raise CommandlineError, _("unknown argument '%{arg}'") % { arg: arg } unless sym
        end

        if given_args.include?(sym) && !@specs[sym][:multi]
          raise CommandlineError, _("option '%{arg}' specified multiple times") % { arg: arg }
        end

        given_args[sym] ||= {}

        given_args[sym][:arg] = arg
        given_args[sym][:params] ||= []

        # The block returns the number of parameters taken.
        num_params_taken = 0

        unless params.nil?
          if SINGLE_ARG_TYPES.include?(@specs[sym][:type])
            given_args[sym][:params] << params[0, 1]  # take the first parameter
            num_params_taken = 1

View on GitHub (pinned to e227c27540)

Solutions

1. Check spelling against `puppet <subcommand> --help`
2. Use dashes, not underscores, in long option names
3. Consult the Puppet release notes if the flag worked on an older version — it may have been renamed or removed
4. As the developer, register the option with opt before parse, or enable ignore_invalid_options in your wrapper if unknown options should pass through

Example fix

# before
$ puppet agent --sever=puppet.example.com --test
Error: Could not parse application options: invalid option: --sever

# after
$ puppet agent --server=puppet.example.com --test

# Validate argv against the registered long/short names before parse (partial-matching is deprecated)
parser = Trollop::Parser.new
# ... declare opts ...
long  = parser.instance_variable_get(:@long)
short = parser.instance_variable_get(:@short)
argv.each do |t|
  if (m = t.match(/^--(?:no-)?([^=]+)/))
    abort "Unknown option #{t}" unless long.key?(m[1])
  elsif (m = t.match(/^-(.)$/))
    abort "Unknown option #{t}" unless short.key?(m[1])
  end
end

begin
  opts = parser.parse(argv)
rescue Puppet::Util::CommandLine::Trollop::CommandlineError => e
  raise unless e.message.include?("unknown argument")
  warn "#{e.message} - run with --help to list valid options"
  exit 64
end
# Through Puppet's own wrapper, rescue instead:
# rescue Puppet::Util::CommandLine::PuppetOptionParser::PuppetOptionError

When it happens

Trigger: `puppet agent --sever=puppet.example.com` (typo in --server); `--node_name` instead of `--node-name`; an option valid for one subcommand passed to another; a flag that was removed or renamed in a newer Puppet version.

Common situations: Typos in long flags; copying flags between puppet subcommands that do not share them; version drift after upgrades where an option no longer exists; long-standing scripts relying on underscore spelling via the deprecated partial matching.

Related errors

• unsupported argument type '%{value0}'
• :type specification and default type don't match (default ty
• invalid long option name %{name}
• long option name %{value0} is already taken; please specify
• invalid short option name '%{name}'

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