puppetlabs/puppet · error · Puppet::DataBinding::LookupError

Function lookup() did not find a value for the name '%{name}

Error message

Function lookup() did not find a value for the name '%{name}'

What it means

Puppet::Pops::Lookup.fail_lookup is the terminal failure of the lookup() function (and automatic parameter lookup) when no value was found for the key in any data source and no default was accepted. It raises Puppet::DataBinding::LookupError with a singular or plural message (n_) depending on whether one name or a list of names was requested. This is the classic 'Hiera key not found' error of Puppet 4.9+/Hiera 5.

Source

Thrown at lib/puppet/pops/lookup.rb:93

      names = names.map { |n| "'#{n}'" }.join(', ')
    end
    "Lookup of #{names}"
  end

  # @api private
  def self.search_and_merge(name, lookup_invocation, merge, apl = true)
    answer = lookup_invocation.lookup_adapter.lookup(name, lookup_invocation, merge)
    lookup_invocation.emit_debug_info("Automatic Parameter Lookup of '#{name}'") if apl && Puppet[:debug]
    answer
  end

  def self.assert_type(subject, type, value)
    type ? Types::TypeAsserter.assert_instance_of(subject, type, value) : value
  end
  private_class_method :assert_type

  def self.fail_lookup(names)
    raise Puppet::DataBinding::LookupError,
          n_("Function lookup() did not find a value for the name '%{name}'",
             "Function lookup() did not find a value for any of the names [%{name_list}]", names.size) % { name: names[0], name_list: names.map { |n| "'#{n}'" }.join(', ') }
  end
  private_class_method :fail_lookup
end
end

require_relative 'lookup/lookup_adapter'
require_relative 'lookup/key_recorder'

View on GitHub (pinned to e227c27540)

Solutions

1. Add the key to a data file that the active hierarchy actually consults (`puppet lookup --explain myapp::port` shows which files were searched and why they missed).
2. Give the caller an out: lookup('myapp::port', String, 'default') or a default_value option; in APL, add a default to the class parameter.
3. Check spelling/casing of the key and any %{...} interpolation in hiera.yaml datadir/hierarchy — a bad interpolation silently redirects the search.
4. Confirm you are in the environment you think (environment=... on the node / lookup invocation), since data is environment-specific.

Example fix

# before
class myapp (
  $port,
) { }
lookup('myapp::port')

# after
class myapp (
  $port = 8080,
) { }
lookup('myapp::port', Integer, 8080)

# Pre-check a key before relying on it (same machinery, no exception)
found = Puppet::Pops::Lookup.lookup('myapp::port', nil, nil, false, nil, :hash, invocation) rescue nil
# or from a manifest/template, probe without failing:
#   $has = lookup('myapp::port', Integer) { |err| undef }  # block form suppresses the raise

begin
  $value = lookup('myapp::port')
rescue Puppet::DataBinding::LookupError => e
  warning("lookup miss: ${e.message}")
  $value = 8080  # safe default
end

When it happens

Trigger: lookup('myapp::port') where no hierarchy layer contains that key and no default_value/default_value_hash option is given; automatic parameter lookup for a class parameter that has no default in the class signature and no matching data key; lookup(['a','b']) missing both names.

Common situations: Key typo or wrong casing; hiera.yaml hierarchy paths pointing to files that do not exist or lack the key; per-node data file missing; forgetting a default; scope interpolation in hiera.yaml producing an unexpected key; environment mismatch so the wrong hierarchy is used.

Related errors

• %{path}: file does not contain a valid yaml hash
• Could not find data item %{key} in any Hiera data file and n
• Unable to parse %{message}
• Unrecognized value for request 'merge' parameter: '%{merge}'
• Unrecognized value for request 'merge' parameter: '#{merge}'

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