puppetlabs/puppet · critical · Puppet::Forge::Errors::ResponseError

Request to Puppet Forge failed. Detail: %{detail}.

Error message

Request to Puppet Forge failed. Detail: %{detail}.

What it means

Puppet's SSL state machine enters the Wait state when the agent has submitted a CSR but holds no signed certificate. waitforcert sets the sleep between checks; when it is below 1 the agent is not allowed to wait at all, so next_state logs this error and calls exit(1). This is the default for one-time runs (puppet agent --test / --onetime), so the first run of a new agent against a CA with manual signing exits immediately after submitting its CSR.

Source

Thrown at lib/puppet/forge.rb:75

  # @raise [Puppet::Forge::Errors::ResponseError] if the repository returns a
  #   bad HTTP response
  def search(term)
    matches = []
    uri = "/v3/modules?query=#{term}"
    if Puppet[:module_groups]
      uri += "&module_groups=#{Puppet[:module_groups].tr('+', ' ')}"
    end

    while uri
      # make_http_request URI encodes parameters
      response = make_http_request(uri)

      if response.code == 200
        result = Puppet::Util::Json.load(response.body)
        uri = decode_uri(result['pagination']['next'])
        matches.concat result['results']
      else
        raise ResponseError.new(:uri => response.url, :response => response)
      end
    end

    matches.each do |mod|
      mod['author'] = mod['owner']['username']
      mod['tag_list'] = mod['current_release']['tags']
      mod['full_name'] = "#{mod['author']}/#{mod['name']}"
      mod['version'] = mod['current_release']['version']
      mod['project_url'] = mod['homepage_url']
      mod['desc'] = mod['current_release']['metadata']['summary'] || ''
    end
  end

  # Fetches {ModuleRelease} entries for each release of the named module.
  #
  # @param input [String] the module name to look up
  # @return [Array<SemanticPuppet::Dependency::ModuleRelease>] a list of releases for
  #         the given name

View on GitHub (pinned to e227c27540)

Solutions

1. Sign the request on the CA: puppetserver ca sign --certname <certname> (puppet cert sign <certname> on legacy masters), then rerun the agent.
2. If signing takes time, allow the agent to wait instead: puppet agent --test --waitforcert 30.
3. Confirm the CSR actually arrived: <ssldir>/certificate_requests/<certname>.pem exists locally and puppetserver ca list shows it on the master.
4. For fleets or short-lived nodes, enable autosigning (autosign.conf or a policy executable) so certificates exist by the first agent run.
5. If the CSR required dns_alt_names, clean and resubmit with --dns_alt_names; a name mismatch means the CA never returns a certificate.

Example fix

# before: one-time run with default waitforcert=0 exits as soon as the CSR is unsigned
puppet agent --test

# after: poll every 30 seconds (bounded by maxwaitforcert) instead of exiting
puppet agent --test --waitforcert 30
# or sign on the CA first:
#   puppetserver ca sign --certname web01.example.com

# Pre-flight: only run a one-time agent when the signed cert already exists
ssldir=$(puppet config print ssldir)
certname=$(puppet config print certname)
if [ ! -f "$ssldir/certs/$certname.pem" ]; then
  echo "CSR not signed yet - run: puppetserver ca sign --certname $certname" >&2
  exit 1
fi
puppet agent --onetime

When it happens

Trigger: Running puppet agent --test (or --onetime) before the CA has signed the node's certificate; waitforcert = 0 in puppet.conf while a CSR is pending; a CSR resubmitted after puppetserver ca clean on a node doing one-time runs. The exit happens on the first Wait transition, before any sleeping.

Common situations: New node bootstraps against a CA with autosigning disabled; CI pipelines that run puppet agent -t before an operator signs; container images that run Puppet once at startup and exit when no certificate is ready.

Related errors

• The certificate for '%{name}' has not yet been signed
• PathPatterns cannot be created with a zero byte.
• The puppet agent command does not take parameters
• An action must be specified.
• Could not submit certificate request for '%{name}' to %{url}

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