puppetlabs/puppet · error

Unable to verify existing FileBucket backup at '%{path}'.

Error message

Unable to verify existing FileBucket backup at '%{path}'.

What it means

Raised while saving to a FileBucket: the existing bucket file carries the same checksum (and checksum type) as the incoming backup, but its actual contents differ — the stored file was corrupted or truncated, or (astronomically unlikely) a hash collision occurred. Puppet refuses to overwrite, logs this error, and raises Puppet::FileBucket::BucketError asking the operator to verify and remove the bad entry.

Source

Thrown at lib/puppet/indirector/file_bucket_file/file.rb:182

        Puppet::FileSystem.exclusive_open(paths_file, 0o640, 'a+:external') do |f|
          if Puppet::FileSystem.exist?(contents_file)
            if verify_identical_file(contents_file, bucket_file)
              # TRANSLATORS "FileBucket" should not be translated
              Puppet.info _("FileBucket got a duplicate file %{file_checksum}") % { file_checksum: bucket_file.checksum }
              # Don't touch the contents file on Windows, since we can't update the
              # mtime of read-only files there.
              unless Puppet::Util::Platform.windows?
                Puppet::FileSystem.touch(contents_file)
              end
            elsif contents_file_matches_checksum?(contents_file, bucket_file.checksum_data, bucket_file.checksum_type)
              # If the contents or sizes don't match, but the checksum does,
              # then we've found a conflict (potential hash collision).
              # Unlikely, but quite bad. Don't remove the file in case it's
              # needed, but ask the user to validate.
              # Note: Don't print the full path to the bucket file in the
              # exception to avoid disclosing file system layout on server.
              # TRANSLATORS "FileBucket" should not be translated
              Puppet.err(_("Unable to verify existing FileBucket backup at '%{path}'.") % { path: contents_file.to_path })
              raise Puppet::FileBucket::BucketError, _("Existing backup and new file have different content but same checksum, %{value}. Verify existing backup and remove if incorrect.") %
                                                     { value: bucket_file.checksum }
            else
              # PUP-1334 If the contents_file exists but does not match its
              # checksum, our backup has been corrupted. Warn about overwriting
              # it, and proceed with new backup.
              Puppet.warning(_("Existing backup does not match its expected sum, %{sum}. Overwriting corrupted backup.") % { sum: bucket_file.checksum })
              copy_bucket_file_to_contents_file(contents_file, bucket_file)
            end
          else
            copy_bucket_file_to_contents_file(contents_file, bucket_file)
          end

          unless path_match(f, files_original_path)
            f.seek(0, IO::SEEK_END)
            f.puts(files_original_path)
          end
        end

View on GitHub (pinned to e227c27540)

Solutions

1. Verify the stored file: compare `md5sum <contents_file>` with the checksum named in the following BucketError message
2. If the stored copy is wrong, remove that bucket entry (the nested checksum path) so the next backup recreates it
3. Restore the correct content from another backup if the bucketed copy mattered
4. Rerun the backup to rebuild the entry cleanly

Example fix

# before
$ puppet filebucket backup large.conf
Error: Unable to verify existing FileBucket backup at '.../contents'.
Error: Existing backup and new file have different content but same checksum...

# after — drop the suspect entry and retry
$ rm -rf <bucket entry dir for that checksum>
$ puppet filebucket backup large.conf

require 'digest'

def bucket_entry_ok?(contents_file, checksum_type, checksum_data)
  Digest.const_get(checksum_type.upcase).file(contents_file.to_s).to_s == checksum_data
end

begin
  Puppet::FileBucket::File.indirection.save(bucket_file, path)
rescue Puppet::FileBucket::BucketError => e
  verify_and_prune_bucket_entry(contents_file)   # compare digests, remove the bad entry
  Puppet::FileBucket::File.indirection.save(bucket_file, path)  # retry once
end

When it happens

Trigger: puppet filebucket backup (or an agent backing up file content) where the contents file under the bucket path exists, its checksum matches the incoming checksum_data/checksum_type, but the byte comparison in the preceding branch already failed — e.g. a truncated or tampered bucket file on disk.

Common situations: Disk corruption or full disks truncating bucket files; backup tools or admins editing bucketed contents; replication or case-insensitive filesystems mangling the bucket tree.

Related errors

• Could not back up %{file}: %{detail}
• File not found
• Existing backup and new file have different content but same
• Unsupported checksum type %{checksum_type}
• Could not back up; will not remove

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