{"record":{"id":"c71d036e58a5b3af","repo":"puppetlabs/puppet","slug":"the-legacy-subcommand-sub-command-does-not-su","errorCode":null,"errorMessage":"The legacy subcommand '%{sub_command}' does not support supplying an action","messagePattern":"The legacy subcommand '%(.+?)' does not support supplying an action","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"lib/puppet/face/help.rb","lineNumber":62,"sourceCode":"      if args.length > 2\n        # TRANSLATORS 'puppet help' is a command line and should not be translated\n        raise ArgumentError, _(\"The 'puppet help' command takes two (optional) arguments: a subcommand and an action\")\n      end\n\n      version = :current\n      if options.has_key? :version\n        if options[:version].to_s !~ /^current$/i\n          version = options[:version]\n        elsif args.length == 0\n          raise ArgumentError, _(\"Supplying a '--version' only makes sense when a Faces subcommand is given\")\n          # TRANSLATORS '--version' is a command line option and should not be translated\n        end\n      end\n\n      facename, actionname = args\n      if legacy_applications.include? facename\n        if actionname\n          raise ArgumentError, _(\"The legacy subcommand '%{sub_command}' does not support supplying an action\") % { sub_command: facename }\n        end\n\n        # legacy apps already emit ronn output\n        return render_application_help(facename)\n      elsif options[:ronn]\n        render_face_man(facename || :help)\n      # Calling `puppet help <app> --ronn` normally calls this action with\n      # <app> as the first argument in the `args` array. However, if <app>\n      # happens to match the name of an action, like `puppet help help\n      # --ronn`, then face_base \"eats\" the argument and `args` will be\n      # empty. Rather than force users to type `puppet help help help\n      # --ronn`, default the facename to `:help`\n      else\n        render_face_help(facename, actionname, version)\n      end\n    end\n  end\n","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/face/help.rb#L44-L80","documentation":"Raised by the `puppet help` Face when the first argument names a legacy (non-Face) application and a second argument (an action name) is also given. Legacy applications (everything in Puppet::Application.available_application_names that is not a Face stub, e.g. agent, apply, describe) pre-date Faces and expose no actions, so `puppet help <legacy-app> <action>` cannot be resolved. Puppet raises ArgumentError before rendering any help text.","triggerScenarios":"Running `puppet help agent <something>` or `puppet help describe <action>`; calling Puppet::Face[:help, :current].call(facename, actionname) where facename is in the legacy_applications list and actionname is non-nil; wrapper scripts that blindly append an action name to every `puppet help X` invocation.","commonSituations":"Users assuming every subcommand supports `<face> <action>` syntax; docs or blog posts written for Face-based subcommands applied to legacy apps; automation that always passes two arguments; Puppet version changes where a subcommand moved between legacy app and Face.","solutions":["Drop the action argument: run `puppet help <legacy-app>` to print that application's help","Get flag-level help directly from the application: `puppet <legacy-app> --help`","If you need action syntax, check `puppet help` output for the Face equivalent of the subcommand and use that name","In Ruby code, strip the action argument when the face name is a legacy application before calling the help face"],"exampleFix":"# before\npuppet help agent certificate\n# after\npuppet help agent\npuppet agent --help","handlingStrategy":"validation","validationCode":"require 'puppet/application'\nface, action =ARGV[0], ARGV[1]\nlegacy = Puppet::Application.available_application_names.reject { |a| Puppet::Face.face?(a) rescue false }\naction = nil if action && legacy.include?(face)\nPuppet::Face[:help, :current].call(*[face, action].compact)","typeGuard":null,"tryCatchPattern":"begin\n  Puppet::Face[:help, :current].call(*args)\nrescue ArgumentError => e\n  warn e.message\n  args = [args.first] # retry with the face name only\n  Puppet::Face[:help, :current].call(*args)\nend","preventionTips":["Treat `puppet help X` as a one-argument command unless X is a known Face","In wrappers, pass the action argument only when `puppet help` lists actions for that subcommand"],"tags":["puppet","cli","faces","usage-error","help"],"backgroundTag":"invalid-cli-arguments","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}