puppetlabs/puppet · error · ArgumentError

The 'puppet help' command takes two (optional) arguments: a

Error message

The 'puppet help' command takes two (optional) arguments: a subcommand and an action

What it means

Usage guard in the `help` face: `puppet help` accepts at most two positional arguments — a subcommand and an action, both optional. Once past the default-case and help-for-help branches, `args.length > 2` raises this ArgumentError before any help text is rendered.

Source

Thrown at lib/puppet/face/help.rb:46

    option "--ronn" do
      summary _("Whether to render the help text in ronn format.")
      default_to { false }
    end

    default
    when_invoked do |*args|
      options = args.pop

      unless options[:ronn]
        if default_case?(args) || help_for_help?(args)
          return erb('global.erb').result(binding)
        end
      end

      if args.length > 2
        # TRANSLATORS 'puppet help' is a command line and should not be translated
        raise ArgumentError, _("The 'puppet help' command takes two (optional) arguments: a subcommand and an action")
      end

      version = :current
      if options.has_key? :version
        if options[:version].to_s !~ /^current$/i
          version = options[:version]
        elsif args.length == 0
          raise ArgumentError, _("Supplying a '--version' only makes sense when a Faces subcommand is given")
          # TRANSLATORS '--version' is a command line option and should not be translated
        end
      end

      facename, actionname = args
      if legacy_applications.include? facename
        if actionname
          raise ArgumentError, _("The legacy subcommand '%{sub_command}' does not support supplying an action") % { sub_command: facename }
        end

View on GitHub (pinned to e227c27540)

Solutions

1. Give at most a subcommand and an action: `puppet help module list`
2. For global usage run plain `puppet help`
3. Constrain wrappers to pass at most two positional tokens to `puppet help`

Example fix

# before
puppet help puppet apply --verbose
# after
puppet help apply

abort 'puppet help takes at most two arguments (subcommand [action])' if args.length > 2

def valid_help_args?(args)
  args.length <= 2
end

When it happens

Trigger: `puppet help apply action extra`, `puppet help module list extra`; passing flags after the action without a separating `--` so they are counted as positionals.

Common situations: Pasting a full command line after `puppet help`; scripts that concatenate a variable argument list onto `puppet help`; users expecting `puppet help` to forward options to the subcommand.

Related errors

• Supplying a '--version' only makes sense when a Faces subcom
• unsupported argument type '%{value0}'
• invalid long option name %{name}
• invalid short option name '%{name}'
• a short option name can't be a number or a dash

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