puppetlabs/puppet · error · Puppet::Error

Failed when searching for node

Error message

Failed when searching for node %{name}: %{detail}

What it means

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.

Solutions

1. 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)
2. Reproduce the lookup directly on the master: puppet node find <name> --terminus <type> --debug
3. If the failure is transient infrastructure, restore the dependency and retry the agent run; no puppet-side config change is needed

Example fix

# before: node_terminus = exec, external_nodes script crashes
# => Puppet::Error: Failed when searching for node node1: undefined method ...

# after: expose and fix the script bug
#   /etc/puppet/node.rb node1.example.com
# fix the reported error, then: puppet agent -t

# ruby
begin
  Puppet::Node.indirection.find(canary_name)
rescue => e
  raise "node terminus unhealthy: #{e}"
end

def node_terminus_healthy?
  Puppet::Node.indirection.find('health-check-placeholder')
  true
rescue StandardError
  false
end

begin
  node = find_node(name, env, nil, nil, nil)
rescue Puppet::Error => e
  Puppet.err(e.message)  # message embeds the underlying detail
  raise if strict_mode
  nil
end

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Could not find node ' '; cannot compile
• Could not call ' ' on
• Facts but no fact format provided for
• Catalog for was requested with fact definition for the…
• Could not find indirection

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

Appendix: source

Thrown at lib/puppet/indirector/catalog/compiler.rb:386

      end
    end

    config
  end

  # Use indirection to find the node associated with a given request
  def find_node(name, environment, transaction_uuid, configured_environment, facts)
    Puppet::Util::Profiler.profile(_("Found node information"), [:compiler, :find_node]) do
      node = nil
      begin
        node = Puppet::Node.indirection.find(name, :environment => environment,
                                                   :transaction_uuid => transaction_uuid,
                                                   :configured_environment => configured_environment,
                                                   :facts => facts)
      rescue => detail
        message = _("Failed when searching for node %{name}: %{detail}") % { name: name, detail: detail }
        Puppet.log_exception(detail, message)
        raise Puppet::Error, message, detail.backtrace
      end

      # Add any external data to the node.
      if node
        add_node_data(node)
      end
      node
    end
  end

  # Extract the node from the request, or use the request
  # to find the node.
  def node_from_request(facts, request)
    node = request.options[:use_node]
    if node
      if request.remote?
        raise Puppet::Error, _("Invalid option use_node for a remote request")
      else

View on GitHub (pinned to e227c27540)