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

Hiera 3 is not installed

Error message

Hiera 3 is not installed

What it means

HieraConfig#create_hiera3_backend_provider builds a provider that delegates to a real Hiera 3 backend library. Its first act is to verify Puppet.features.hiera? — that the hiera gem/library can be loaded. If not, it raises Puppet::DataBinding::LookupError 'Hiera 3 is not installed' before touching Hiera::Config. Puppet's built-in lookup (Hiera 5) does not need the gem, so this error only appears when configuration explicitly asks for a Hiera 3 backend.

Source

Thrown at lib/puppet/pops/lookup/hiera_config.rb:290

  def create_configured_data_providers(lookup_invocation, parent_data_provider, use_default_hierarchy)
    self.class.not_implemented(self, 'create_configured_data_providers')
  end

  def validate_config(config, owner)
    self.class.not_implemented(self, 'validate_config')
  end

  def version
    self.class.not_implemented(self, 'version')
  end

  def name
    "hiera configuration version #{version}"
  end

  def create_hiera3_backend_provider(name, backend, parent_data_provider, datadir, paths, hiera3_config)
    # Custom backend. Hiera 3 must be installed, its logger configured, and it must be made aware of the loaded config
    raise Puppet::DataBinding::LookupError, 'Hiera 3 is not installed' unless Puppet.features.hiera?

    if Hiera::Config.instance_variable_defined?(:@config) && (current_config = Hiera::Config.instance_variable_get(:@config)).is_a?(Hash)
      current_config.each_pair do |key, val|
        case key
        when :hierarchy, :backends
          hiera3_config[key] = ([val] + [hiera3_config[key]]).flatten.uniq
        else
          hiera3_config[key] = val
        end
      end
    elsif hiera3_config.include?(KEY_LOGGER)
      Hiera.logger = hiera3_config[KEY_LOGGER].to_s
    else
      Hiera.logger = 'puppet'
    end

    unless Hiera::Interpolate.const_defined?(:PATCHED_BY_HIERA_5)
      # Replace the class methods 'hiera_interpolate' and 'alias_interpolate' with a method that wires back and performs global

View on GitHub (pinned to e227c27540)

Solutions

1. Refactor the backend to a native Hiera 5 provider: a data_hash, lookup_key, or data_dig function in a module, and declare it in a version-5 hiera.yaml.
2. Use the built-in yaml/json data_hash backends for plain data.
3. Only if you must stay on Hiera 3 semantics: install the hiera 3 library so Puppet.features.hiera? becomes true (version-compatible with your Puppet).

Example fix

# before: hiera.yaml (v3)
:backends:
  - mycustom
:mycustom:
  :datadir: /etc/puppet/data

# after: hiera.yaml (version 5) using a module function backend
version: 5
defaults:
  datadir: data
  data_hash: yaml_data
hierarchy:
  - name: custom
    data_hash: mymodule::custom_data

# Fail early with a clear message when config needs Hiera 3 but it is absent
raise LoadError, 'hiera.yaml uses a Hiera 3 backend; install hiera or migrate to a version-5 provider' \
  if config_references_hiera3_backend?(hiera_yaml) && !Puppet.features.hiera?

def config_references_hiera3_backend?(path)
  content = File.read(path)
  content.match?(/:backends:|hiera3_backend/) || content.match?(/^version:\s*3/)
end

begin
  lookup('myapp::config')
rescue Puppet::DataBinding::LookupError => e
  raise unless e.message == 'Hiera 3 is not installed'
  # fall back to the pure-Puppet data source if you maintain one
  $config = load_default_config
end

When it happens

Trigger: A hierarchy entry (typically a converted hiera.yaml v3 config or a v5 config using a legacy/custom backend) that routes to a Hiera 3 backend while the puppet installation has no hiera library — gem-installed Puppet without the hiera gem, or a Puppet version whose packaging dropped Hiera 3.

Common situations: Upgrading Puppet where Hiera 3 support was removed; hiera.yaml v3 configs still referencing custom backends (e.g. custom backend gems) now driven through Puppet's lookup; legacy modules shipping a hiera.yaml with :backends entries Puppet cannot serve.

Related errors

• Undefined variable '%{name}'; %{reason}
• Could not find data item %{key} in any Hiera data file and n
• Please supply a parameter to perform a Hiera lookup
• %{path}: file does not contain a valid yaml hash
• Unable to parse %{message}

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