{"record":{"id":"197a41d41f52bcc9","repo":"puppetlabs/puppet","slug":"hiera-3-is-not-installed","errorCode":null,"errorMessage":"Hiera 3 is not installed","messagePattern":"Hiera 3 is not installed","errorType":"exception","errorClass":"Puppet::DataBinding::LookupError","httpStatus":null,"severity":"error","filePath":"lib/puppet/pops/lookup/hiera_config.rb","lineNumber":290,"sourceCode":"  def create_configured_data_providers(lookup_invocation, parent_data_provider, use_default_hierarchy)\n    self.class.not_implemented(self, 'create_configured_data_providers')\n  end\n\n  def validate_config(config, owner)\n    self.class.not_implemented(self, 'validate_config')\n  end\n\n  def version\n    self.class.not_implemented(self, 'version')\n  end\n\n  def name\n    \"hiera configuration version #{version}\"\n  end\n\n  def create_hiera3_backend_provider(name, backend, parent_data_provider, datadir, paths, hiera3_config)\n    # Custom backend. Hiera 3 must be installed, its logger configured, and it must be made aware of the loaded config\n    raise Puppet::DataBinding::LookupError, 'Hiera 3 is not installed' unless Puppet.features.hiera?\n\n    if Hiera::Config.instance_variable_defined?(:@config) && (current_config = Hiera::Config.instance_variable_get(:@config)).is_a?(Hash)\n      current_config.each_pair do |key, val|\n        case key\n        when :hierarchy, :backends\n          hiera3_config[key] = ([val] + [hiera3_config[key]]).flatten.uniq\n        else\n          hiera3_config[key] = val\n        end\n      end\n    elsif hiera3_config.include?(KEY_LOGGER)\n      Hiera.logger = hiera3_config[KEY_LOGGER].to_s\n    else\n      Hiera.logger = 'puppet'\n    end\n\n    unless Hiera::Interpolate.const_defined?(:PATCHED_BY_HIERA_5)\n      # Replace the class methods 'hiera_interpolate' and 'alias_interpolate' with a method that wires back and performs global","sourceCodeStart":272,"sourceCodeEnd":308,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/pops/lookup/hiera_config.rb#L272-L308","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Use the built-in yaml/json data_hash backends for plain data.","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)."],"exampleFix":"# before: hiera.yaml (v3)\n:backends:\n  - mycustom\n:mycustom:\n  :datadir: /etc/puppet/data\n\n# after: hiera.yaml (version 5) using a module function backend\nversion: 5\ndefaults:\n  datadir: data\n  data_hash: yaml_data\nhierarchy:\n  - name: custom\n    data_hash: mymodule::custom_data","handlingStrategy":"validation","validationCode":"# Fail early with a clear message when config needs Hiera 3 but it is absent\nraise LoadError, 'hiera.yaml uses a Hiera 3 backend; install hiera or migrate to a version-5 provider' \\\n  if config_references_hiera3_backend?(hiera_yaml) && !Puppet.features.hiera?\n\ndef config_references_hiera3_backend?(path)\n  content = File.read(path)\n  content.match?(/:backends:|hiera3_backend/) || content.match?(/^version:\\s*3/)\nend","typeGuard":null,"tryCatchPattern":"begin\n  lookup('myapp::config')\nrescue Puppet::DataBinding::LookupError => e\n  raise unless e.message == 'Hiera 3 is not installed'\n  # fall back to the pure-Puppet data source if you maintain one\n  $config = load_default_config\nend","preventionTips":["Migrate hiera.yaml to version 5 with native data_hash/lookup_key/data_dig function providers.","Do not let v3 configs with custom :backends linger after Puppet upgrades; audit on every major upgrade.","Check Puppet.features.hiera? in smoke tests when any legacy backend remains in use."],"tags":["puppet","hiera","hiera3","backends","missing-dependency"],"backgroundTag":"hiera3-not-installed","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}