{"record":{"id":"396c4dc73a094285","repo":"puppetlabs/puppet","slug":"find-uri-resulted-in-404-with-the-message-bo-396c4d","errorCode":null,"errorMessage":"Find %{uri} resulted in 404 with the message: %{body}","messagePattern":"Find %(.+?) resulted in 404 with the message: %(.+?)","errorType":"http","errorClass":"Puppet::Error","httpStatus":404,"severity":"error","filePath":"lib/puppet/indirector/node/rest.rb","lineNumber":26,"sourceCode":"    to override its environment.\"\n\n  def find(request)\n    session = Puppet.lookup(:http_session)\n    api = session.route_to(:puppet)\n    _, node = api.get_node(\n      request.key,\n      environment: request.environment.to_s,\n      configured_environment: request.options[:configured_environment],\n      transaction_uuid: request.options[:transaction_uuid]\n    )\n    node\n  rescue Puppet::HTTP::ResponseError => e\n    if e.response.code == 404\n      return nil unless request.options[:fail_on_404]\n\n      _, body = parse_response(e.response)\n      msg = _(\"Find %{uri} resulted in 404 with the message: %{body}\") % { uri: elide(e.response.url.path, 100), body: body }\n      raise Puppet::Error, msg\n    else\n      raise convert_to_http_error(e.response)\n    end\n  end\nend\n","sourceCodeStart":8,"sourceCodeEnd":32,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/indirector/node/rest.rb#L8-L32","documentation":"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.","triggerScenarios":"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/...","commonSituations":"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.","solutions":["Verify the certname the agent presents matches what the server expects: puppet config print certname, and check the certificate with puppet ssl show_certificate","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","Ensure the node exists in the ENC/classifier backing node_terminus (add it, or fix node_terminus config)","Check auth.conf / puppetserver routing rules have not removed access to the node endpoint","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)"],"exampleFix":"# before: agent run fails\n# Error: Find /puppet/v3/node/web01.example.com resulted in 404 with the message: Not Found: Could not find node web01.example.com\n\n# after: register the node in the classifier (or add it to site.pp flow)\n# 1. confirm server-side view\ncurl -sk --cert /etc/puppetlabs/puppet/ssl/certs/pe-server.pem \\\n     --key /etc/puppetlabs/puppet/ssl/private_keys/pe-server.pem \\\n     'https://puppet:8140/puppet/v3/node/web01.example.com?environment=production'\n# 2. add web01.example.com to the ENC / node group, then re-run\npuppet agent -t","handlingStrategy":"try-catch","validationCode":"uri = \"#{Puppet[:server]}:#{Puppet[:masterport]}\"\n# probe cert recognition before agent run\ncode = `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\nPuppet.warning \"node endpoint returned #{code}\" unless code == '200'","typeGuard":null,"tryCatchPattern":"begin\n  node = Puppet::Node.indirection.find(\n    certname, environment: env, fail_on_404: false  # do not hard-fail on 404\n  )\nrescue Puppet::HTTP::ResponseError => e\n  retry_once = (e.response.code == 404)\n  raise\nend","preventionTips":["Register new nodes in the classifier/ENC before their first agent run","Omit fail_on_404 in custom node lookups when site.pp fallback is acceptable","Monitor 404 rates on /puppet/v3/node/ in server access logs to catch classifier drift early"],"tags":["puppet","rest","http-404","node-lookup","classifier"],"backgroundTag":"http-404-not-found","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}