puppetlabs/puppet · error

Run `puppet agent -t`

Error message

Run `puppet agent -t`

What it means

Printed by Puppet::HTTP::Client#default_ssl_context as the remediation hint after any exception while building the SSL context — missing or unreadable CA, CRL, key, or cert (errors 1120-1125), or a bad key password. The original failure is logged first as 'Failed to initialize SSL: <message>', then this hint, then the exception is re-raised.

Source

Thrown at lib/puppet/http/client.rb:322

  def close
    @pool.close
    @default_ssl_context = nil
    @default_system_ssl_context = nil
  end

  def default_ssl_context
    cert = Puppet::X509::CertProvider.new
    password = cert.load_private_key_password

    ssl = Puppet::SSL::SSLProvider.new
    ctx = ssl.load_context(certname: Puppet[:certname], password: password)
    ssl.print(ctx)
    ctx
  rescue => e
    # TRANSLATORS: `message` is an already translated string of why SSL failed to initialize
    Puppet.log_exception(e, _("Failed to initialize SSL: %{message}") % { message: e.message })
    # TRANSLATORS: `puppet agent -t` is a command and should not be translated
    Puppet.err(_("Run `puppet agent -t`"))
    raise e
  end

  protected

  def encode_query(url, params)
    return url if params.empty?

    url = url.dup
    url.query = encode_params(params)
    url
  end

  private

  # Connect or borrow a connection from the pool to the host and port associated
  # with the request's URL. Then execute the HTTP request, retrying and
  # following redirects as needed, and return the HTTP response. The response

View on GitHub (pinned to e227c27540)

Solutions

1. Read the preceding 'Failed to initialize SSL:' log line — it carries the root cause
2. Run `puppet agent -t` (or `puppet ssl provision`) to fetch the missing CA/CRL and submit the CSR
3. Verify identity files: `puppet config print localcacert hostcrl hostcert hostprivkey` and confirm each exists and is readable
4. Re-enroll the node if the key or cert is unrecoverable

%w[localcacert hostcrl hostcert hostprivkey].each do |setting|
  path = Puppet[setting]
  abort "#{setting} missing or empty at #{path}" if path && !File.size?(path)
end

begin
  response = Puppet::HTTP::Client.new.get(uri)
rescue StandardError => e
  warn 'SSL not provisioned — run `puppet agent -t` before using HTTP APIs' if ssl_related?(e)
  raise
end

When it happens

Trigger: Any Puppet::HTTP request path that calls default_ssl_context on a node whose SSL material is incomplete or corrupt; typically the first network touch of puppet agent, puppet ssl, or HTTP API calls after a broken or absent bootstrap.

Common situations: Unbootstrapped nodes; lost private keys; mismatched certname; cloned or partially restored ssl dirs; encrypted key password mismatches.

Related errors

• The CA certificates are missing from '%{path}'
• Failed to parse CA certificates as PEM
• The CRL is missing from '%{path}'
• Failed to parse CRLs as PEM
• The private key is missing from '%{path}'

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