puppetlabs/puppet · error · Puppet::Error

Could not back up %{file}: %{detail}

Error message

Could not back up %{file}: %{detail}

What it means

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.

Source

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

    raise(ArgumentError, _("File %{file} does not exist") % { file: file }) unless Puppet::FileSystem.exist?(file_handle)

    begin
      file_bucket_file = Puppet::FileBucket::File.new(file_handle, :bucket_path => @local_path)
      files_original_path = absolutize_path(file)
      dest_path = "#{@rest_path}#{file_bucket_file.name}/#{files_original_path}"
      file_bucket_path = "#{@rest_path}#{file_bucket_file.checksum_type}/#{file_bucket_file.checksum_data}/#{files_original_path}"

      # Make a HEAD request for the file so that we don't waste time
      # uploading it if it already exists in the bucket.
      unless Puppet::FileBucket::File.indirection.head(file_bucket_path, :bucket_path => file_bucket_file.bucket_path)
        Puppet::FileBucket::File.indirection.save(file_bucket_file, dest_path)
      end

      file_bucket_file.checksum_data
    rescue => detail
      message = _("Could not back up %{file}: %{detail}") % { file: file, detail: detail }
      Puppet.log_exception(detail, message)
      raise Puppet::Error, message, detail.backtrace
    end
  end

  # Diffs two filebucket files identified by their sums
  def diff(checksum_a, checksum_b, file_a, file_b)
    raise RuntimeError, _("Diff is not supported on this platform") if Puppet[:diff] == ""

    if checksum_a
      source_path = "#{@rest_path}#{@checksum_type}/#{checksum_a}"
      if checksum_b
        file_diff = Puppet::FileBucket::File.indirection.find(
          source_path,
          :bucket_path => @local_path,
          :diff_with => checksum_b
        )
      elsif file_b
        tmp_file = ::Tempfile.new('diff')
        begin

View on GitHub (pinned to e227c27540)

Solutions

1. Read the %{detail} suffix first — it names the actual failure (network, permissions, checksum)
2. For remote buckets, confirm the server setting (`puppet agent --configprint server`, filebucket section) and test connectivity to port 8140
3. For local buckets, confirm the bucket directory is writable by the effective user (`puppet agent --configprint bucketdir`, then check permissions)
4. Fix the underlying cause from the detail message and retry the backup

Example fix

# before: [main] filebucket server unreachable
# after: verify connectivity, then re-run
curl -s -o /dev/null -w '%{http_code}' https://puppet.example.com:8140/production/file_bucket_file/md5/...
puppet filebucket backup /etc/puppetlabs/puppet/puppet.conf

def backup_target_ready?(file)
  Puppet::FileSystem.exist?(file) && File.readable?(file)
end

begin
  dipper.backup(path)
rescue Puppet::Error => e
  Puppet.warning "bucket backup skipped for #{path}: #{e.message}"
  # e.message suffix carries the root cause; do not retry blindly on permission errors
end

When it happens

Trigger: `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.

Common situations: 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.

Related errors

• Could not back up; will not remove
• Will not remove directory backup %{newfile}; use a filebucke
• Unable to verify existing FileBucket backup at '%{path}'.
• Need exactly two arguments: filebucket diff <file_a> <file_b
• Diff is not supported on this platform

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