puppetlabs/puppet · error · Puppet::Error

Find %{uri} resulted in 404 with the message: %{body}

Error message

Find %{uri} resulted in 404 with the message: %{body}

What it means

The REST node terminus requested a node from the Puppet Server and got a 404. A 404 normally means 'node not found' and returns nil so compilation can fall back to site.pp, but when the request carries options[:fail_on_404] = true (which Puppet's configurer sets when fetching its node before compiling a catalog), the 404 is converted into a hard Puppet::Error including the URI path and the server's response body.

Source

Thrown at lib/puppet/indirector/node/rest.rb:26

    to override its environment."

  def find(request)
    session = Puppet.lookup(:http_session)
    api = session.route_to(:puppet)
    _, node = api.get_node(
      request.key,
      environment: request.environment.to_s,
      configured_environment: request.options[:configured_environment],
      transaction_uuid: request.options[:transaction_uuid]
    )
    node
  rescue Puppet::HTTP::ResponseError => e
    if e.response.code == 404
      return nil unless request.options[:fail_on_404]

      _, body = parse_response(e.response)
      msg = _("Find %{uri} resulted in 404 with the message: %{body}") % { uri: elide(e.response.url.path, 100), body: body }
      raise Puppet::Error, msg
    else
      raise convert_to_http_error(e.response)
    end
  end
end

View on GitHub (pinned to e227c27540)

Solutions

1. Verify the certname the agent presents matches what the server expects: puppet config print certname, and check the certificate with puppet ssl show_certificate
2. On the server, test the node endpoint directly: curl --cert <paths> https://server:8140/puppet/v3/node/<certname>?environment=production and read the response body echoed in the error
3. Ensure the node exists in the ENC/classifier backing node_terminus (add it, or fix node_terminus config)
4. Check auth.conf / puppetserver routing rules have not removed access to the node endpoint
5. If the fallback-to-site.pp behavior is desired, ensure the lookup is not made with fail_on_404 (that option is set internally by the configurer; custom tooling can omit it)

Example fix

# before: agent run fails
# Error: Find /puppet/v3/node/web01.example.com resulted in 404 with the message: Not Found: Could not find node web01.example.com

# after: register the node in the classifier (or add it to site.pp flow)
# 1. confirm server-side view
curl -sk --cert /etc/puppetlabs/puppet/ssl/certs/pe-server.pem \
     --key /etc/puppetlabs/puppet/ssl/private_keys/pe-server.pem \
     'https://puppet:8140/puppet/v3/node/web01.example.com?environment=production'
# 2. add web01.example.com to the ENC / node group, then re-run
puppet agent -t

uri = "#{Puppet[:server]}:#{Puppet[:masterport]}"
# probe cert recognition before agent run
code = `curl -sk -o /dev/null -w '%{http_code}' --cert /etc/puppetlabs/puppet/ssl/certs/#{certname}.pem --key /etc/puppetlabs/puppet/ssl/private_keys/#{certname}.pem https://#{uri}/puppet/v3/node/#{certname}?environment=production`.strip
Puppet.warning "node endpoint returned #{code}" unless code == '200'

begin
  node = Puppet::Node.indirection.find(
    certname, environment: env, fail_on_404: false  # do not hard-fail on 404
  )
rescue Puppet::HTTP::ResponseError => e
  retry_once = (e.response.code == 404)
  raise
end

When it happens

Trigger: Agent run where configurer calls Puppet::Node.indirection.find with fail_on_404: true and the server's node endpoint returns 404: certname not present in an external node classifier / node_terminus that returns nil, stale or missing certificate causing the server to not recognize the node, or a proxy/route mismatch returning 404 for /puppet/v3/node/...

Common situations: First run of a new node whose certname isn't in the classifier; classifier (PE console, PuppetDB-based ENC) missing the node after a rename; puppetserver route/auth layering changed so the node endpoint 404s; agents pointing at the wrong server URL.

Related errors

• HTTP REST queries cannot handle values of type '%{klass}'
• Listing remote file buckets is not allowed
• Find %{uri} resulted in 404 with the message: %{body}
• Find %{uri} resulted in 404 with the message: %{body}
• Not authorized to call %{method} on %{description}

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