puppetlabs/puppet · error · Puppet::Error

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

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.

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)

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 '%{name}'; cannot compile
• Facts but no fact format provided for %{request}
• Could not call '%{method}' on '%{indirection}': %{detail}
• Catalog for %{request} was requested with fact definition fo
• Unsupported facts format

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