puppetlabs/puppet · error · Puppet::Error

Could not back up; will not remove

Error message

Could not back up; will not remove

What it means

When a managed file must be removed or replaced, Puppet first backs it up via `perform_backup`. `backup_existing` raises Puppet::Error 'Could not back up; will not remove' when that returns false — Puppet then leaves the file untouched rather than destroying it without a backup.

Source

Thrown at lib/puppet/type/file.rb:1065

  def remove_file(current_type, wanted_type)
    debug "Removing existing #{current_type} for replacement with #{wanted_type}"
    Puppet::FileSystem.unlink(self[:path])
    stat_needed
    true
  end

  def stat_needed
    @stat = :needs_stat
  end

  # Back up the existing file at a given prior to it being removed
  # @api private
  # @raise [Puppet::Error] if the file backup failed
  # @return [void]
  def backup_existing
    unless perform_backup
      # TRANSLATORS refers to a file which could not be backed up
      raise Puppet::Error, _("Could not back up; will not remove")
    end
  end

  # Make sure the file we wrote out is what we think it is.
  # @param [Puppet::Parameter] property the param or property that wrote the file, or nil
  # @param [String] path to the file
  # @param [String] the checksum for the local file
  #
  # @api private
  #
  def fail_if_checksum_is_wrong(property, path, content_checksum)
    desired_checksum = desired_checksum(property, path)

    if desired_checksum && content_checksum != desired_checksum
      self.fail _("File written to disk did not match desired checksum; discarding changes (%{content_checksum} vs %{desired_checksum})") % { content_checksum: content_checksum, desired_checksum: desired_checksum }
    end
  end

View on GitHub (pinned to e227c27540)

Solutions

1. Set `backup => false` on file resources you intentionally replace without backups.
2. Verify the local bucket: clientbucketdir must exist and be writable by the agent (owned puppet:puppet, mode 0750+).
3. Verify a remote bucket resolves and is reachable before the next run.
4. Run `puppet agent -t --debug` to see the underlying perform_backup failure detail.

Example fix

// before: replacing a file while the bucket is broken
filebucket { 'main':
  path   => false,
  server => 'puppet.example.com',  // unreachable
}
file { '/etc/app.conf':
  ensure => file,
  source => 'puppet:///modules/app/app.conf',
  backup => 'main',
}

// after: this file does not need a backup
file { '/etc/app.conf':
  ensure => file,
  source => 'puppet:///modules/app/app.conf',
  backup => false,
}

# Ruby pre-flight on the agent side
dir = Puppet[:clientbucketdir]
if Puppet[:bucket].nil? && (!Puppet::FileSystem.exist?(dir) || !File.writable?(dir))
  fail("#{dir} missing or not writable — fix the bucket or set backup => false on files you replace")
end

rescue Puppet::Error => e; if e.message =~ /Could not back up/ then repair the backup target (permissions or reachability) before the next run, or explicitly decline backups with `backup => false` on that file resource — never delete the target file without deciding the backup policy.

When it happens

Trigger: A file resource replacing an existing file while the backup target is unusable: a remote filebucket whose `server` is unreachable, `clientbucketdir` not writable by the agent user, `backup` referencing an undefined filebucket, or a read-only filesystem for the local bucket.

Common situations: Central filebucket server down or firewalled during a run; agent running as non-root against a root-owned clientbucketdir; SELinux denials on /var/lib/puppet; Puppet 8 defaults routing backups through the main bucket with a misconfigured server_list.

Related errors

• Could not back up %{file}: %{detail}
• Could not read #{ftype} #{resource.title}: #{detail}
• Could not remove existing file
• Will not remove directory backup %{newfile}; use a filebucke
• Unable to verify existing FileBucket backup at '%{path}'.

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