puppetlabs/puppet · error · Puppet::Error

Failed to read %{target}'s records when prefetching them. Re

Error message

Failed to read %{target}'s records when prefetching them. Reason: %{detail}

What it means

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.

Source

Thrown at lib/puppet/provider/parsedfile.rb:104

    end
  end

  # Make sure our file is backed up, but only back it up once per transaction.
  # We cheat and rely on the fact that @records is created on each prefetch.
  def self.backup_target(target)
    return nil unless target_object(target).respond_to?(:backup)

    @backup_stats ||= {}
    return nil if @backup_stats[target] == @records.object_id

    target_object(target).backup
    @backup_stats[target] = @records.object_id
  end

  # Flush all of the records relating to a specific target.
  def self.flush_target(target)
    if @raise_prefetch_errors && @failed_prefetch_targets.key?(target)
      raise Puppet::Error, _("Failed to read %{target}'s records when prefetching them. Reason: %{detail}") % { target: target, detail: @failed_prefetch_targets[target] }
    end

    backup_target(target)

    records = target_records(target).reject { |r|
      r[:ensure] == :absent
    }

    target_object(target).write(to_file(records))
  end

  # Return the header placed at the top of each generated file, warning
  # users that modifying this file manually is probably a bad idea.
  def self.header
    %(# HEADER: This file was autogenerated at #{Time.now}
# HEADER: by puppet.  While it can still be managed manually, it
# HEADER: is definitely not recommended.\n)
  end

View on GitHub (pinned to e227c27540)

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

Example fix

# before: /etc/hosts contains an unparseable line
999.999.999.999	bogus-host

# after: valid address, tabs/spaces as the parsed provider expects
10.0.0.99	bogus-host.example.com	bogus-host

Defensive patterns

Strategy: validation

Validate before calling

# reproduce the prefetch read early, without flushing anything
Puppet::Type.type(:host).provider(:parsed).instances
# raises the same parse/read error the flush would, during a --noop or pre-flight run

Try / catch

begin
  provider.flush
rescue Puppet::Error => e
  # message carries target + detail; do NOT retry — the file on disk is suspect
  log "prefetch failure on target, manual inspection required: #{e.message}"
end

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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