puppetlabs/puppet · error · CommandlineError

option '%{arg}' needs a parameter

Error message

option '%{arg}' needs a parameter

What it means

After token resolution, parse converts each option's collected parameters; at trollop.rb:422 any option whose type is not :flag but whose params array is empty raises CommandlineError "option '--x' needs a parameter". Params end up empty when the option is the last token on the command line, or when the next token already looks like an option so each_arg claims it as a new option instead of a value (trollop.rb:603-607).

Source

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

        case type
        when :depends
          syms.each { |sym| raise CommandlineError, _("--%{value0} requires --%{value1}") % { value0: @specs[constraint_sym][:long], value1: @specs[sym][:long] } unless given_args.include? sym }
        when :conflicts
          syms.each { |sym| raise CommandlineError, _("--%{value0} conflicts with --%{value1}") % { value0: @specs[constraint_sym][:long], value1: @specs[sym][:long] } if given_args.include?(sym) && (sym != constraint_sym) }
        end
      end

      required.each do |sym, _val|
        raise CommandlineError, _("option --%{opt} must be specified") % { opt: @specs[sym][:long] } unless given_args.include? sym
      end

      ## parse parameters
      given_args.each do |sym, given_data|
        arg = given_data[:arg]
        params = given_data[:params]

        opts = @specs[sym]
        raise CommandlineError, _("option '%{arg}' needs a parameter") % { arg: arg } if params.empty? && opts[:type] != :flag

        vals["#{sym}_given".intern] = true # mark argument as specified on the commandline

        case opts[:type]
        when :flag
          if arg =~ /^--no-/ and sym.to_s =~ /^--\[no-\]/
            vals[sym] = opts[:default]
          else
            vals[sym] = !opts[:default]
          end
        when :int, :ints
          vals[sym] = params.map { |pg| pg.map { |p| parse_integer_parameter p, arg } }
        when :float, :floats
          vals[sym] = params.map { |pg| pg.map { |p| parse_float_parameter p, arg } }
        when :string, :strings
          vals[sym] = params.map { |pg| pg.map(&:to_s) }
        when :io, :ios
          vals[sym] = params.map { |pg| pg.map { |p| parse_io_parameter p, arg } }

View on GitHub (pinned to e227c27540)

Solutions

1. Append the value directly: `--server puppet.example.com`
2. Use the equals form `--server=puppet.example.com` (trollop.rb:600) so the value cannot be stolen by the next token
3. For dash-prefixed values, always use the `--opt=value` form
4. Quote and sanity-check programmatically generated command lines before executing them

Example fix

# before
$ mytool --server --verbose
Error: option '--server' needs a parameter

# after
$ mytool --server=host.example.com --verbose

# Detect value-taking options whose value is missing or dash-prefixed before parse
flag_names = %w[server environment ca]   # your value-taking long options
argv.each_with_index do |t, i|
  name = t[/^--([^=]+)$/, 1]
  next unless name && flag_names.include?(name)
  nxt = argv[i + 1]
  abort "#{t} needs a value - use #{t}=<value>" if nxt.nil? || nxt.start_with?('-')
end

begin
  opts = parser.parse(argv)
rescue Puppet::Util::CommandLine::Trollop::CommandlineError => e
  raise unless e.message.include?('needs a parameter')
  name = e.message[/option '(.+)' needs/, 1]
  abort "#{name} requires a value (hint: use #{name}=<value>, especially for values starting with '-')"
end

When it happens

Trigger: `puppet agent --server` as the last argument; `--server --verbose` (the following token is consumed as an option, leaving --server valueless); a value that itself begins with a dash being classified as an option token.

Common situations: Truncated command lines from shell history editing; scripts dropping the value argument; negative numbers or dash-prefixed values that the parser treats as flags.

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