puppetlabs/puppet · error · Puppet::Error

Extra arguments detected: %{args} Did you mean to run: pup

Error message

Extra arguments detected: %{args}
Did you mean to run:
  puppetserver ca clean --certname <name>
Or:
  puppet ssl clean --target <name>

What it means

Thrown by the `clean` action of the `puppet ssl` application when extra positional arguments remain after the action name (the code checks `command_line.args.drop(1)` and requires it to be empty). `puppet ssl clean` takes no certname argument; it only cleans the SSL files of the host running the command, so any extra token is treated as a probable mistake. The message deliberately points at the two commands that do accept a name: `puppetserver ca clean --certname` (on the CA) and `puppet ssl clean --target` (for the target agent).

Source

Thrown at lib/puppet/application/ssl.rb:152

        cert = download_cert(ssl_context)
        unless cert
          Puppet.info(_("The certificate for '%{name}' has not yet been signed") % { name: certname })
        end
      end
    when 'download_cert'
      ssl_context = @machine.ensure_ca_certificates
      cert = download_cert(ssl_context)
      unless cert
        raise Puppet::Error, _("The certificate for '%{name}' has not yet been signed") % { name: certname }
      end
    when 'generate_request'
      generate_request(certname)
    when 'verify'
      verify(certname)
    when 'clean'
      possible_extra_args = command_line.args.drop(1)
      unless possible_extra_args.empty?
        raise Puppet::Error, _(<<~END) % { args: possible_extra_args.join(' ') }
          Extra arguments detected: %{args}
          Did you mean to run:
            puppetserver ca clean --certname <name>
          Or:
            puppet ssl clean --target <name>
        END
      end

      clean(certname)
    when 'bootstrap'
      unless Puppet::Util::Log.sendlevel?(:info)
        Puppet::Util::Log.level = :info
      end
      @machine.ensure_client_certificate
      Puppet.notice(_("Completed SSL initialization"))
    when 'show'
      show(certname)
    else

View on GitHub (pinned to e227c27540)

Solutions

1. Drop the extra argument: run plain `puppet ssl clean` — it removes this host's cert, private key, public key, and CSR
2. To remove a certificate for another node, run `puppetserver ca clean --certname <name>` on the CA host
3. To clean a different target agent, use `puppet ssl clean --target <name>` as the error suggests
4. Audit wrapper scripts that pass a certname positionally and strip it before invoking puppet

Example fix

# before
puppet ssl clean node1.example.com
# => Extra arguments detected: node1.example.com
# after
puppet ssl clean                        # cleans this host
# on the CA instead:
puppetserver ca clean --certname node1.example.com

# mirror the app's own check before shelling out
action = ARGV[0]
extra  = ARGV.drop(1)
if action == 'clean' && !extra.empty?
  abort "puppet ssl clean takes no extra arguments (got: #{extra.join(' ')})"
end
system('puppet', 'ssl', *ARGV)

def ssl_clean_args_valid?(argv)
  return true unless argv[0] == 'clean'
  argv.drop(1).empty?
end

When it happens

Trigger: Running `puppet ssl clean node1.example.com`, or `puppet ssl clean --certname node1` where the unknown flag is not consumed by the option parser and lands in command_line.args; any automation or wrapper that appends a hostname after the `clean` action.

Common situations: Muscle memory from `puppet cert clean <name>` or `puppetserver ca clean --certname <name>`; scripts written for the old certificate face; runbooks copied from Puppet 5-era documentation; CI jobs parameterized with a node name that always gets appended.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• Unknown action '%{action}'
• The certificate %{certname} must be cleaned from the CA firs
• Error parsing arguments
• The puppet agent command does not take parameters
• puppet %{face} %{action} takes %{arg_count} argument, but yo

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