What causes "Could not find node '%{name}'; cannot compile" in puppetlabs/puppet?

Check the terminus first: run puppet node find --debug on the master to see exactly what the node terminus returns

puppetlabs/puppet · error · ArgumentError

Could not find node '%{name}'; cannot compile

Error message

Could not find node '%{name}'; cannot compile

What it means

In the catalog compiler, when neither options[:use_node] nor a successful node lookup produces a node (Puppet::Node.indirection.find returns nil), ArgumentError 'Could not find node ...; cannot compile' is raised. Unlike the wrapped-lookup error, nothing threw — the configured node terminus simply had no entry for the requested name.

Source

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

      else
        return node
      end
    end

    # We rely on our authorization system to determine whether the connected
    # node is allowed to compile the catalog's node referenced by key.
    # By default the REST authorization system makes sure only the connected node
    # can compile his catalog.
    # This allows for instance monitoring systems or puppet-load to check several
    # node's catalog with only one certificate and a modification to auth.conf
    # If no key is provided we can only compile the currently connected node.
    name = request.key || request.node
    node = find_node(name, request.environment, request.options[:transaction_uuid], request.options[:configured_environment], facts)
    if node
      return node
    end

    raise ArgumentError, _("Could not find node '%{name}'; cannot compile") % { name: name }
  end

  # Initialize our server fact hash; we add these to each client, and they
  # won't change while we're running, so it's safe to cache the values.
  #
  # See also set_server_facts in Puppet::Server::Compiler in puppetserver.
  def set_server_facts
    @server_facts = Puppet::Node::ServerFacts.load
  end
end

View on GitHub (pinned to e227c27540)

Solutions

Check the terminus first: run puppet node find <certname> --debug on the master to see exactly what the node terminus returns
If using an ENC, make it return a YAML classification for the node (empty or whitespace means not found)
Fix name mismatches: align certname with what the terminus keys on (watch case and trailing dot)
As a fallback, switch node_terminus to plain and rely on site.pp defaults

Example fix

# before: ENC returns nothing for new nodes
#  => ArgumentError: Could not find node 'node1.example.com'; cannot compile

# after: ENC emits yaml for the node
#   printf 'classes: [base]\nenvironment: production\n' | /etc/puppet/node.rb node1.example.com
# then: puppet agent -t

Defensive patterns

Strategy: try-catch

Validate before calling

# ruby
node = Puppet::Node.indirection.find(certname)
raise ArgumentError, "node #{certname} unresolvable via #{Puppet[:node_terminus]}" if node.nil?

Type guard

def node_known?(name)
  !Puppet::Node.indirection.find(name).nil?
end

Try / catch

begin
  compiler.node_from_request(facts, request)
rescue ArgumentError => e
  raise unless e.message.include?('Could not find node')
  nil  # investigate terminus (ENC output, name normalization)
end

Prevention

Give ENCs an explicit default-class branch instead of returning empty for unknown nodes
Alert on repeated node-lookup failures — they usually mean ENC or LDAP gaps
Normalize names: watch trailing dots and case differences between certname and node data

When it happens

Trigger: node_terminus = plain with no node definition matching the certname; an ENC returning an empty document for the node (empty response is treated as not found); an LDAP query succeeding but matching no entry; requesting a catalog for a name that differs by case or trailing dot from the stored node name.

Common situations: ENC returning empty output for a new node; node_terminus=plain on a master with no matching node statement or site.pp entry; certname case or FQDN trailing-dot differences between the request and node data.

Related errors

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