{"record":{"id":"60016e0e173a9ef2","repo":"puppetlabs/puppet","slug":"find-uri-resulted-in-404-with-the-message-bo","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/catalog/rest.rb","lineNumber":46,"sourceCode":"    _, catalog = api.post_catalog(\n      request.key,\n      facts: request.options[:facts_for_catalog],\n      environment: request.environment.to_s,\n      configured_environment: request.options[:configured_environment],\n      check_environment: request.options[:check_environment],\n      transaction_uuid: request.options[:transaction_uuid],\n      job_uuid: request.options[:job_id],\n      static_catalog: request.options[:static_catalog],\n      checksum_type: checksum_type\n    )\n    catalog\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":28,"sourceCodeEnd":52,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/indirector/catalog/rest.rb#L28-L52","documentation":"The catalog REST terminus turns a server 404 into a Puppet::Error whose message embeds the request path and the server's response body — but only when the request carried options[:fail_on_404] truthy; otherwise a 404 maps to nil (catalog not found). This preserves the indirector convention that find returns nil for missing resources while letting agent runs fail loudly on a missing catalog.","triggerScenarios":"Puppet::Resource::Catalog.indirection.find(name, fail_on_404: true) against a server that answers 404 (unknown node, unknown environment, or a request routed to a server without the node's data); agent runs, which set fail_on_404 so a missing catalog aborts instead of silently returning nil.","commonSituations":"The requested environment does not exist on the master (common after environment renames); a load balancer or SRV routing sending the catalog GET to a compile server that does not know the node; agents pointing at a compile-masters tier during migration.","solutions":["Read the body in the message — puppetserver's 404 body states what was not found (node vs environment); fix that on the server side","Verify the agent's environment setting and that the environment exists on the master before failing hard","If nil-not-found semantics are wanted (tooling), call find without fail_on_404"],"exampleFix":"# before (ruby)\ncatalog = Puppet::Resource::Catalog.indirection.find(name,\n  fail_on_404: true)  # 404 => Puppet::Error\n\n# after: tolerate missing catalogs\ncatalog = Puppet::Resource::Catalog.indirection.find(name)  # 404 => nil","handlingStrategy":"try-catch","validationCode":"# ruby\n# choose semantics before the call; only pass fail_on_404 when missing is fatal\ncatalog = Puppet::Resource::Catalog.indirection.find(name)\nraise 'catalog missing' if catalog.nil? && strict","typeGuard":"def catalog_present?(name)\n  !Puppet::Resource::Catalog.indirection.find(name).nil?\nend","tryCatchPattern":"begin\n  Puppet::Resource::Catalog.indirection.find(name, fail_on_404: true)\nrescue Puppet::Error => e\n  raise unless e.message.include?('404')\n  nil  # or retry against the primary master if routed to a compile server\nend","preventionTips":["Reserve fail_on_404 for agent-run paths where nil would hide broken compilation","Read the 404 body before assuming network trouble — it names the missing node or environment","In inventory scripts, prefer default nil-semantics find and handle nil explicitly"],"tags":["puppet-rest","catalog","http-404","indirector"],"backgroundTag":"http-404-resource-not-found","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}