{"record":{"id":"41785d514c74ace8","repo":"puppetlabs/puppet","slug":"could-not-back-up-file-detail","errorCode":null,"errorMessage":"Could not back up %{file}: %{detail}","messagePattern":"Could not back up %(.+?): %(.+?)","errorType":"exception","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/file_bucket/dipper.rb","lineNumber":59,"sourceCode":"    raise(ArgumentError, _(\"File %{file} does not exist\") % { file: file }) unless Puppet::FileSystem.exist?(file_handle)\n\n    begin\n      file_bucket_file = Puppet::FileBucket::File.new(file_handle, :bucket_path => @local_path)\n      files_original_path = absolutize_path(file)\n      dest_path = \"#{@rest_path}#{file_bucket_file.name}/#{files_original_path}\"\n      file_bucket_path = \"#{@rest_path}#{file_bucket_file.checksum_type}/#{file_bucket_file.checksum_data}/#{files_original_path}\"\n\n      # Make a HEAD request for the file so that we don't waste time\n      # uploading it if it already exists in the bucket.\n      unless Puppet::FileBucket::File.indirection.head(file_bucket_path, :bucket_path => file_bucket_file.bucket_path)\n        Puppet::FileBucket::File.indirection.save(file_bucket_file, dest_path)\n      end\n\n      file_bucket_file.checksum_data\n    rescue => detail\n      message = _(\"Could not back up %{file}: %{detail}\") % { file: file, detail: detail }\n      Puppet.log_exception(detail, message)\n      raise Puppet::Error, message, detail.backtrace\n    end\n  end\n\n  # Diffs two filebucket files identified by their sums\n  def diff(checksum_a, checksum_b, file_a, file_b)\n    raise RuntimeError, _(\"Diff is not supported on this platform\") if Puppet[:diff] == \"\"\n\n    if checksum_a\n      source_path = \"#{@rest_path}#{@checksum_type}/#{checksum_a}\"\n      if checksum_b\n        file_diff = Puppet::FileBucket::File.indirection.find(\n          source_path,\n          :bucket_path => @local_path,\n          :diff_with => checksum_b\n        )\n      elsif file_b\n        tmp_file = ::Tempfile.new('diff')\n        begin","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/file_bucket/dipper.rb#L41-L77","documentation":"Dipper#backup streams a file into the filebucket (a local directory or a remote Puppet Server) through the FileBucket indirection: a HEAD request checks presence, then the file is saved. Any exception from those calls is logged and re-raised as Puppet::Error 'Could not back up <file>: <detail>' — the %{detail} suffix carries the real cause, such as connection refused or permission denied.","triggerScenarios":"`puppet filebucket backup /path/file` or an agent run with puppet.conf routing the filebucket to a `server` that is down or unreachable on port 8140; a local bucketdir that is not writable by the puppet user; a file that vanishes between the existence check and the save.","commonSituations":"Filebucket server entry removed after infrastructure changes; SELinux or ownership denials on the bucket directory; agents configured with a read-only or unmounted bucket path; firewalls blocking 8140.","solutions":["Read the %{detail} suffix first — it names the actual failure (network, permissions, checksum)","For remote buckets, confirm the server setting (`puppet agent --configprint server`, filebucket section) and test connectivity to port 8140","For local buckets, confirm the bucket directory is writable by the effective user (`puppet agent --configprint bucketdir`, then check permissions)","Fix the underlying cause from the detail message and retry the backup"],"exampleFix":"# before: [main] filebucket server unreachable\n# after: verify connectivity, then re-run\ncurl -s -o /dev/null -w '%{http_code}' https://puppet.example.com:8140/production/file_bucket_file/md5/...\npuppet filebucket backup /etc/puppetlabs/puppet/puppet.conf","handlingStrategy":"try-catch","validationCode":"def backup_target_ready?(file)\n  Puppet::FileSystem.exist?(file) && File.readable?(file)\nend","typeGuard":null,"tryCatchPattern":"begin\n  dipper.backup(path)\nrescue Puppet::Error => e\n  Puppet.warning \"bucket backup skipped for #{path}: #{e.message}\"\n  # e.message suffix carries the root cause; do not retry blindly on permission errors\nend","preventionTips":["Verify bucketdir writability for the puppet user before agent runs (logrotate-style preflight)","Monitor the filebucket server endpoint in health checks so agents fail loud, not per-file","Read the %{detail} suffix before changing configuration — it distinguishes network from permission causes"],"tags":["puppet","filebucket","backup","network","permissions"],"backgroundTag":"file-backup-failed","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}