puppetlabs/puppet · error · Puppet::Error

File not found

Error message

File not found

What it means

Dipper#get_bucket_file looks up a content blob by checksum via the FileBucket indirection (local bucketdir or remote server). When the find returns nil, the checksum is unknown to that bucket and Puppet::Error 'File not found' is raised. getfile and restore both funnel through this method, so every retrieval of an unknown sum fails here.

Solutions

1. Confirm the content exists where you are looking: `puppet filebucket find <sum>` (with the same --local/server settings), or list the local bucket
2. Re-populate the bucket: `puppet filebucket backup <file>`, then retry
3. Verify the settings match the ones used at backup time (bucketdir / server) and that digest_algorithm is unchanged

Example fix

# before
puppet filebucket get 3c0b7f2d1a8e...  # File not found
# after: re-backup from the surviving copy, then retrieve
puppet filebucket backup /backup/puppet.conf
puppet filebucket get 3c0b7f2d1a8e...

sum = sum.to_s.downcase
raise ArgumentError, 'not an md5/sha256 hex sum' unless sum.match?(/\A[0-9a-f]{32,64}\z/)

begin
  content = dipper.getfile(sum)
rescue Puppet::Error => e
  raise unless e.message == 'File not found'
  nil # caller decides: restore from another source, or re-backup
end

When it happens

Trigger: `puppet filebucket get <sum>` for content never backed up into that bucket; restore() of a sum after the bucket directory was wiped; querying a server-side bucket for content stored only locally; digest algorithm changed (md5 vs sha256) so sums do not match.

Common situations: Disaster-recovery attempts after bucket cleanup; mixed local/server bucket configurations; sums copied by hand with typos; Puppet upgrades that changed digest_algorithm.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Existing backup and new file have different content but…
• Unable to verify existing FileBucket backup at
• Unsupported checksum type
• binary_file(): The given file
• Could not ' '; module has had changes made locally

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

Appendix: source

Thrown at lib/puppet/file_bucket/dipper.rb:116

        file_diff = Puppet::Util::Diff.diff(file_a, file_b)
      end
    end
    raise Puppet::Error, _("Failed to diff files") unless file_diff

    file_diff.to_s
  end

  # Retrieves a file by sum.
  def getfile(sum)
    get_bucket_file(sum).to_s
  end

  # Retrieves a FileBucket::File by sum.
  def get_bucket_file(sum)
    source_path = "#{@rest_path}#{@checksum_type}/#{sum}"
    file_bucket_file = Puppet::FileBucket::File.indirection.find(source_path, :bucket_path => @local_path)

    raise Puppet::Error, _("File not found") unless file_bucket_file

    file_bucket_file
  end

  # Restores the file
  def restore(file, sum)
    restore = true
    file_handle = Puppet::FileSystem.pathname(file)
    if Puppet::FileSystem.exist?(file_handle)
      cursum = Puppet::FileBucket::File.new(file_handle).checksum_data()

      # if the checksum has changed...
      # this might be extra effort
      if cursum == sum
        restore = false
      end
    end

View on GitHub (pinned to e227c27540)