{"record":{"id":"8d3e7fd92ad4ff0a","repo":"puppetlabs/puppet","slug":"failed-when-searching-for-node-name-detail","errorCode":null,"errorMessage":"Failed when searching for node %{name}: %{detail}","messagePattern":"Failed when searching for node %(.+?): %(.+?)","errorType":"exception","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/indirector/catalog/compiler.rb","lineNumber":386,"sourceCode":"      end\n    end\n\n    config\n  end\n\n  # Use indirection to find the node associated with a given request\n  def find_node(name, environment, transaction_uuid, configured_environment, facts)\n    Puppet::Util::Profiler.profile(_(\"Found node information\"), [:compiler, :find_node]) do\n      node = nil\n      begin\n        node = Puppet::Node.indirection.find(name, :environment => environment,\n                                                   :transaction_uuid => transaction_uuid,\n                                                   :configured_environment => configured_environment,\n                                                   :facts => facts)\n      rescue => detail\n        message = _(\"Failed when searching for node %{name}: %{detail}\") % { name: name, detail: detail }\n        Puppet.log_exception(detail, message)\n        raise Puppet::Error, message, detail.backtrace\n      end\n\n      # Add any external data to the node.\n      if node\n        add_node_data(node)\n      end\n      node\n    end\n  end\n\n  # Extract the node from the request, or use the request\n  # to find the node.\n  def node_from_request(facts, request)\n    node = request.options[:use_node]\n    if node\n      if request.remote?\n        raise Puppet::Error, _(\"Invalid option use_node for a remote request\")\n      else","sourceCodeStart":368,"sourceCodeEnd":404,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/indirector/catalog/compiler.rb#L368-L404","documentation":"The compiler's find_node wraps Puppet::Node.indirection.find in error handling: if the configured node terminus (plain, exec, ldap, etc.) raises while looking up the node, the exception is logged via Puppet.log_exception and re-raised as Puppet::Error with the original detail message embedded. The underlying cause is always visible in the interpolated detail text and the log entry.","triggerScenarios":"node_terminus = exec and the ENC script exits non-zero or is missing; node_terminus = ldap with the LDAP server down or bind credentials wrong; a database-backed node terminus failing during an outage — any exception inside Puppet::Node.indirection.find during a catalog request.","commonSituations":"ENC (external node classifier) script broken after a deploy, missing a gem, or not executable; LDAP connectivity or firewall issues on the master; storeconfigs/database outages during maintenance windows.","solutions":["Read the detail portion of the message — it names the real failure; fix the terminus it points to (repair or debug the ENC, restore LDAP, fix the DB)","Reproduce the lookup directly on the master: puppet node find <name> --terminus <type> --debug","If the failure is transient infrastructure, restore the dependency and retry the agent run; no puppet-side config change is needed"],"exampleFix":"# before: node_terminus = exec, external_nodes script crashes\n# => Puppet::Error: Failed when searching for node node1: undefined method ...\n\n# after: expose and fix the script bug\n#   /etc/puppet/node.rb node1.example.com\n# fix the reported error, then: puppet agent -t","handlingStrategy":"try-catch","validationCode":"# ruby\nbegin\n  Puppet::Node.indirection.find(canary_name)\nrescue => e\n  raise \"node terminus unhealthy: #{e}\"\nend","typeGuard":"def node_terminus_healthy?\n  Puppet::Node.indirection.find('health-check-placeholder')\n  true\nrescue StandardError\n  false\nend","tryCatchPattern":"begin\n  node = find_node(name, env, nil, nil, nil)\nrescue Puppet::Error => e\n  Puppet.err(e.message)  # message embeds the underlying detail\n  raise if strict_mode\n  nil\nend","preventionTips":["Monitor the ENC/LDAP/DB dependency behind the node terminus; this error is a symptom, not the cause","Add a 'puppet node find <canary>' health check to master monitoring","Keep ENC scripts minimal and run them in CI with sample node names"],"tags":["puppet-compiler","node-lookup","enc","indirector","wrapper-error"],"backgroundTag":"node-lookup-failed","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}