puppetlabs/puppet · error · CommandlineError

invalid argument syntax: '%{arg}'

Error message

invalid argument syntax: '%{arg}'

What it means

During Parser#parse, each_arg yields every option-looking token and the case at trollop.rb:334-361 classifies it: a single-dash single-character short ('-x'), a negated long ('--no-name'), or a plain long whose first character after '--' is not a dash. A token that survives each_arg but fits none of these shapes — typically a long flag with three or more leading dashes — hits the else branch at line 360 and raises CommandlineError. Note that the arg terminator '--' is handled separately (trollop.rb:597) and short bundling like '-vh' is split by each_arg, so neither triggers this error.

Source

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

                    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
              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

View on GitHub (pinned to e227c27540)

Solutions

1. Type the flag with exactly two dashes: `--debug`
2. Inspect the exact token named in the message for stray leading dashes
3. If you build flags programmatically, strip existing leading dashes before adding the '--' prefix
4. Run `<command> --help` and copy the exact spelling shown

Example fix

# before
$ mytool ---verbose
Error: invalid argument syntax: '---verbose'

# after
$ mytool --verbose

# Reject malformed flag tokens before parsing (mirrors the classifier at trollop.rb:334-361)
bad = argv.grep(/^--+/).select { |t| t !~ /^--no-([^-]\S*)$/ && t !~ /^--([^-]\S*)$/ && t !~ /^-([^-])$/ }
abort "Malformed argument(s): #{bad.join(' ')} - use exactly two leading dashes" unless bad.empty?

begin
  opts = Puppet::Util::CommandLine::Trollop::Parser.new { /* opts */ }.parse(argv)
rescue Puppet::Util::CommandLine::Trollop::CommandlineError => e
  if e.message.include?('invalid argument syntax')
    warn "#{e.message} (check for extra leading dashes)"
    exit 64   # EX_USAGE
  end
  raise
end

When it happens

Trigger: `mytool ---debug` (three dashes: each_arg yields '---debug', which matches no branch); any '--' immediately followed by another dash; a long flag assembled programmatically that prefixes '--' to a string already containing dashes.

Common situations: Manual typing or tab-completion inserting an extra leading dash; flags copied from documentation, chat, or rich text that mangled the dashes; generated command lines that double up the '--' prefix.

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/b52c868b3a79edaf. Report an issue: GitHub.