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.

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)

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.

Related errors

• Existing backup and new file have different content but same
• Unsupported checksum type %{checksum_type}
• Unable to verify existing FileBucket backup at '%{path}'.
• Need exactly two arguments: filebucket diff <file_a> <file_b
• One or more file(s) specified did not exist: %{files}

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