puppetlabs/puppet · error · ArgumentError

Supplying a '--version' only makes sense when a Faces subcom

Error message

Supplying a '--version' only makes sense when a Faces subcommand is given

What it means

Usage guard in the `help` face for `--version`: the option selects which version of a Faces subcommand's help to render, so it only makes sense together with a subcommand. Per the code it fires when `--version` was supplied, its value matched `current` case-insensitively, and no positional subcommand argument was given — i.e. `puppet help --version current` with nothing else. Note this is help-rendering version selection; printing Puppet's own version is `puppet --version`.

Source

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

      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

        # legacy apps already emit ronn output
        return render_application_help(facename)
      elsif options[:ronn]
        render_face_man(facename || :help)
      # Calling `puppet help <app> --ronn` normally calls this action with
      # <app> as the first argument in the `args` array. However, if <app>
      # happens to match the name of an action, like `puppet help help
      # --ronn`, then face_base "eats" the argument and `args` will be

View on GitHub (pinned to e227c27540)

Solutions

1. Add the subcommand: `puppet help apply --version current`
2. Or drop the flag: `puppet help`
3. For Puppet's own version use `puppet --version`, not `puppet help --version`

Example fix

# before
puppet help --version current
# after
puppet help apply --version current
# or
puppet --version

abort '--version requires a subcommand' if options.key?(:version) && args.empty?

When it happens

Trigger: `puppet help --version current` with no subcommand; wrappers that unconditionally inject `--version <%= v %>` into every `puppet help` invocation, including global help.

Common situations: Templated help commands in scripts; misunderstanding `--version` here as a way to print Puppet's version; tab-completed leftovers from an older CLI.

Related errors

• The 'puppet help' command takes two (optional) arguments: a
• Error parsing arguments
• The puppet agent command does not take parameters
• puppet %{face} %{action} takes %{arg_count} argument, but yo
• Need exactly two arguments: filebucket diff <file_a> <file_b

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