What causes "'%{face}' has no %{action} action. See `puppet help %{face}`." in puppetlabs/puppet?

Run `puppet help ` (e.g. `puppet help module`) and use an action from that list

'%{face}' has no %{action} action. See `puppet help %{face}

Error message

'%{face}' has no %{action} action.  See `puppet help %{face}`.

What it means

Emitted by Puppet::Application::FaceBase (face_base.rb:139) when the invoked face has no action with the requested name, or no default action when none is given (action renders as 'default'). The runner prints the message, flushes the log queue, and exits with failure status. It is CLI argument validation, not an exception callers can rescue.

Source

Thrown at lib/puppet/application/face_base.rb:139

    if @action.nil?
      @action = @face.get_default_action()
      if @action
        @is_default_action = true
      else
        # First try to handle global command line options
        # But ignoring invalid options as this is a invalid action, and
        # we want the error message for that instead.
        begin
          super
        rescue OptionParser::InvalidOption
        end

        face   = @face.name
        action = action_name.nil? ? 'default' : "'#{action_name}'"
        msg = _("'%{face}' has no %{action} action.  See `puppet help %{face}`.") % { face: face, action: action }

        Puppet.err(msg)
        Puppet::Util::Log.force_flushqueue()

        exit false
      end
    end

    # Now we can interact with the default option code to build behaviour
    # around the full set of options we now know we support.
    @action.options.each do |o|
      o = @action.get_option(o) # make it the object.
      self.class.option(*o.optparse) # ...and make the CLI parse it.
    end

    # ...and invoke our parent to parse all the command line options.
    super
  end

  def find_global_settings_argument(item)

View on GitHub (pinned to e227c27540)

Solutions

Run `puppet help <face>` (e.g. `puppet help module`) and use an action from that list
Fix the typo and rerun the command
Compare `puppet --version` across machines and align versions if the action is missing in the older one
For custom faces, verify the plugin is installed and discoverable before invoking it

Example fix

# before
$ puppet module instal puppetlabs-apt
Error: 'module' has no 'instal' action.  See `puppet help module`.

# after
$ puppet module install puppetlabs-apt

Defensive patterns

Strategy: validation

Validate before calling

require 'puppet/face'

face = Puppet::Face[:module, :current]
action = ARGV[0]
unless face.actions.map(&:to_s).include?(action)
  abort "unknown action '#{action}'; valid actions: #{face.actions.join(', ')}"
end

Type guard

def known_action?(face, name)
  !face.get_action(name.to_sym).nil?
end

Prevention

Pin wrapper scripts to a tested Puppet version and exercise them in CI
Generate CLI usage from `puppet help <face>` in docs instead of hand-writing action names
Fail fast on unknown subcommands before doing side-effectful work

When it happens

Trigger: Running `puppet <face> <bogus-action>` — a typo, a removed action, or the wrong subcommand — e.g. `puppet module instal puppetlabs-apt`. Also hitting it programmatically by calling a face whose current version does not define the requested action symbol.

Common situations: Command-line typos; scripts written for a different Puppet version where an action was renamed or removed; custom faces not installed or plugin-synced to the node; tab-completion mistakes in runbooks.

Related errors

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