{"record":{"id":"106493f40b259253","repo":"puppetlabs/puppet","slug":"failed-to-read-target-s-records-when-prefetchin","errorCode":null,"errorMessage":"Failed to read %{target}'s records when prefetching them. Reason: %{detail}","messagePattern":"Failed to read %(.+?)'s records when prefetching them\\. Reason: %(.+?)","errorType":"exception","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/provider/parsedfile.rb","lineNumber":104,"sourceCode":"    end\n  end\n\n  # Make sure our file is backed up, but only back it up once per transaction.\n  # We cheat and rely on the fact that @records is created on each prefetch.\n  def self.backup_target(target)\n    return nil unless target_object(target).respond_to?(:backup)\n\n    @backup_stats ||= {}\n    return nil if @backup_stats[target] == @records.object_id\n\n    target_object(target).backup\n    @backup_stats[target] = @records.object_id\n  end\n\n  # Flush all of the records relating to a specific target.\n  def self.flush_target(target)\n    if @raise_prefetch_errors && @failed_prefetch_targets.key?(target)\n      raise Puppet::Error, _(\"Failed to read %{target}'s records when prefetching them. Reason: %{detail}\") % { target: target, detail: @failed_prefetch_targets[target] }\n    end\n\n    backup_target(target)\n\n    records = target_records(target).reject { |r|\n      r[:ensure] == :absent\n    }\n\n    target_object(target).write(to_file(records))\n  end\n\n  # Return the header placed at the top of each generated file, warning\n  # users that modifying this file manually is probably a bad idea.\n  def self.header\n    %(# HEADER: This file was autogenerated at #{Time.now}\n# HEADER: by puppet.  While it can still be managed manually, it\n# HEADER: is definitely not recommended.\\n)\n  end","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/provider/parsedfile.rb#L86-L122","documentation":"ParsedFile-based providers (host, port, mailalias, etc.) read every target file during prefetch before flushing changes. When reading a target fails, the failure is stored per-target in @failed_prefetch_targets; at flush time flush_target re-raises it as a Puppet::Error when the provider class has raise_prefetch_errors enabled. This deferred raise is a safety mechanism: it stops Puppet from rewriting a file whose current contents it could not read or parse, which would otherwise destroy unknown records.","triggerScenarios":"A resource backed by a ParsedFile provider (e.g. host resources over /etc/hosts) where target_records/prefetch hits an unreadable, missing, or unparseable file; the catalog still compiles and prefetch completes, then the error fires inside flush_target right before backup_target and target_object(target).write would run, and only when @raise_prefetch_errors is true for that provider class.","commonSituations":"A hand-edited /etc/hosts or /etc/services line with syntax the provider's parser rejects; the target file with root-only permissions while the agent runs reduced; NFS-mounted file unavailable at prefetch time; a prior partial write that left the file corrupt.","solutions":["Read the %{detail} in the message: it names the exact read/parse failure and usually the offending line of the target file","Fix or remove the malformed entry in the target file manually, then re-run the agent","Verify the agent (or the user running puppet) can read the target: ls -l on the path from the error","If the file was truncated/corrupted, restore it from backup or your VCS before the next puppet run, because flush will not proceed but a provider with raise_prefetch_errors disabled would have overwritten it"],"exampleFix":"# before: /etc/hosts contains an unparseable line\n999.999.999.999\tbogus-host\n\n# after: valid address, tabs/spaces as the parsed provider expects\n10.0.0.99\tbogus-host.example.com\tbogus-host","handlingStrategy":"validation","validationCode":"# reproduce the prefetch read early, without flushing anything\nPuppet::Type.type(:host).provider(:parsed).instances\n# raises the same parse/read error the flush would, during a --noop or pre-flight run","typeGuard":null,"tryCatchPattern":"begin\n  provider.flush\nrescue Puppet::Error => e\n  # message carries target + detail; do NOT retry — the file on disk is suspect\n  log \"prefetch failure on target, manual inspection required: #{e.message}\"\nend","preventionTips":["Keep managed target files (/etc/hosts, /etc/services) under VCS or file resources so unparseable hand-edits surface at change time","Run puppet agent --noop or a pre-flight provider .instances check after risky manual edits","Give the agent user read access to all provider targets; avoid NFS-soft mounts for /etc files","Treat any 'prefetching' warning in logs as a stop signal, not noise, when raise_prefetch_errors providers are in play"],"tags":["puppet","parsedfile","prefetch","flush","file-parse"],"backgroundTag":"file-parse-failure","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}