puppetlabs/puppet · error · Puppet::Indirector::ValidationError

Instance name %{name} does not match requested key %{key}

Error message

Instance name %{name} does not match requested key %{key}

What it means

The base Terminus#validate_key requires that when a request carries an instance, request.key equals instance.name exactly (both are inspected in the message). It runs during Terminus#validate on write-path operations (save/head) for termini that validate requests, catching the case where a caller names an object differently from the key under which it is being stored — e.g., saving a node whose .name is 'web01' under key 'web01.example.com'.

Source

Thrown at lib/puppet/indirector/terminus.rb:171

  def allow_remote_requests?
    true
  end

  def terminus_type
    self.class.terminus_type
  end

  def validate(request)
    if request.instance
      validate_model(request)
      validate_key(request)
    end
  end

  def validate_key(request)
    unless request.key == request.instance.name
      raise Puppet::Indirector::ValidationError, _("Instance name %{name} does not match requested key %{key}") % { name: request.instance.name.inspect, key: request.key.inspect }
    end
  end

  def validate_model(request)
    unless model === request.instance
      raise Puppet::Indirector::ValidationError, _("Invalid instance type %{klass}, expected %{model_type}") % { klass: request.instance.class.inspect, model_type: model.inspect }
    end
  end
end

View on GitHub (pinned to e227c27540)

Solutions

1. Always pass the instance's own name as the key: indirection.save(instance, instance.name)
2. If a different storage key is required, set instance.name to that value before saving
3. Search the code path for any mutation of .name after request creation and move it before the request is built
4. Compare the two inspected values in the error message to spot whitespace/case drift quickly

Example fix

# before
facts = Puppet::Node::Facts.new('web01', values)
Puppet::Node::Facts.indirection.save(facts, 'web01.example.com')
# => Instance name "web01" does not match requested key "web01.example.com"

# after
facts = Puppet::Node::Facts.new('web01.example.com', values)
Puppet::Node::Facts.indirection.save(facts, 'web01.example.com')

if request.instance && request.instance.respond_to?(:name) && request.key != request.instance.name
  raise Puppet::Indirector::ValidationError, "key #{request.key.inspect} != name #{request.instance.name.inspect}"
end

def name_matches_key?(instance, key)
  instance.respond_to?(:name) && instance.name == key
end

When it happens

Trigger: Calling indirection.save(instance, key) or constructing a request whose key differs from instance.name: Puppet::Node.indirection.save(node, node.name + '.example.com'), or deserialized instances whose name was mutated after the request key was computed.

Common situations: Tooling that stores objects under FQDN keys while the object's name is the short hostname (or vice versa); normalize-name functions applied to one side but not the other; test fixtures hard-coding keys that drift from fixture data.

Related errors

• Resource instance does not match request key
• Invalid instance type %{klass}, expected %{model_type}
• invalid key
• One or more file(s) specified did not exist: %{files}
• a data type must have an interface

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