{"record":{"id":"afe3d6ee9cb58156","repo":"puppetlabs/puppet","slug":"unable-to-verify-existing-filebucket-backup-at","errorCode":null,"errorMessage":"Unable to verify existing FileBucket backup at '%{path}'.","messagePattern":"Unable to verify existing FileBucket backup at '%(.+?)'\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"lib/puppet/indirector/file_bucket_file/file.rb","lineNumber":182,"sourceCode":"        Puppet::FileSystem.exclusive_open(paths_file, 0o640, 'a+:external') do |f|\n          if Puppet::FileSystem.exist?(contents_file)\n            if verify_identical_file(contents_file, bucket_file)\n              # TRANSLATORS \"FileBucket\" should not be translated\n              Puppet.info _(\"FileBucket got a duplicate file %{file_checksum}\") % { file_checksum: bucket_file.checksum }\n              # Don't touch the contents file on Windows, since we can't update the\n              # mtime of read-only files there.\n              unless Puppet::Util::Platform.windows?\n                Puppet::FileSystem.touch(contents_file)\n              end\n            elsif contents_file_matches_checksum?(contents_file, bucket_file.checksum_data, bucket_file.checksum_type)\n              # If the contents or sizes don't match, but the checksum does,\n              # then we've found a conflict (potential hash collision).\n              # Unlikely, but quite bad. Don't remove the file in case it's\n              # needed, but ask the user to validate.\n              # Note: Don't print the full path to the bucket file in the\n              # exception to avoid disclosing file system layout on server.\n              # TRANSLATORS \"FileBucket\" should not be translated\n              Puppet.err(_(\"Unable to verify existing FileBucket backup at '%{path}'.\") % { path: contents_file.to_path })\n              raise Puppet::FileBucket::BucketError, _(\"Existing backup and new file have different content but same checksum, %{value}. Verify existing backup and remove if incorrect.\") %\n                                                     { value: bucket_file.checksum }\n            else\n              # PUP-1334 If the contents_file exists but does not match its\n              # checksum, our backup has been corrupted. Warn about overwriting\n              # it, and proceed with new backup.\n              Puppet.warning(_(\"Existing backup does not match its expected sum, %{sum}. Overwriting corrupted backup.\") % { sum: bucket_file.checksum })\n              copy_bucket_file_to_contents_file(contents_file, bucket_file)\n            end\n          else\n            copy_bucket_file_to_contents_file(contents_file, bucket_file)\n          end\n\n          unless path_match(f, files_original_path)\n            f.seek(0, IO::SEEK_END)\n            f.puts(files_original_path)\n          end\n        end","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/indirector/file_bucket_file/file.rb#L164-L200","documentation":"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.","triggerScenarios":"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.","commonSituations":"Disk corruption or full disks truncating bucket files; backup tools or admins editing bucketed contents; replication or case-insensitive filesystems mangling the bucket tree.","solutions":["Verify the stored file: compare `md5sum <contents_file>` with the checksum named in the following BucketError message","If the stored copy is wrong, remove that bucket entry (the nested checksum path) so the next backup recreates it","Restore the correct content from another backup if the bucketed copy mattered","Rerun the backup to rebuild the entry cleanly"],"exampleFix":"# before\n$ puppet filebucket backup large.conf\nError: Unable to verify existing FileBucket backup at '.../contents'.\nError: Existing backup and new file have different content but same checksum...\n\n# after — drop the suspect entry and retry\n$ rm -rf <bucket entry dir for that checksum>\n$ puppet filebucket backup large.conf","handlingStrategy":"try-catch","validationCode":"require 'digest'\n\ndef bucket_entry_ok?(contents_file, checksum_type, checksum_data)\n  Digest.const_get(checksum_type.upcase).file(contents_file.to_s).to_s == checksum_data\nend","typeGuard":null,"tryCatchPattern":"begin\n  Puppet::FileBucket::File.indirection.save(bucket_file, path)\nrescue Puppet::FileBucket::BucketError => e\n  verify_and_prune_bucket_entry(contents_file)   # compare digests, remove the bad entry\n  Puppet::FileBucket::File.indirection.save(bucket_file, path)  # retry once\nend","preventionTips":["Monitor bucket directory integrity (unexpected size/type drift) and disk space","Exclude the bucket tree from tools that rewrite or 'normalize' files","Treat a checksum match with mismatched bytes as corruption until proven otherwise"],"tags":["ruby","puppet","filebucket","checksum","backup","corruption","md5"],"backgroundTag":"file-checksum-mismatch","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}