{"record":{"id":"d764c6be72868a22","repo":"puppetlabs/puppet","slug":"could-not-back-up-will-not-remove","errorCode":null,"errorMessage":"Could not back up; will not remove","messagePattern":"Could not back up; will not remove","errorType":"exception","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/type/file.rb","lineNumber":1065,"sourceCode":"  def remove_file(current_type, wanted_type)\n    debug \"Removing existing #{current_type} for replacement with #{wanted_type}\"\n    Puppet::FileSystem.unlink(self[:path])\n    stat_needed\n    true\n  end\n\n  def stat_needed\n    @stat = :needs_stat\n  end\n\n  # Back up the existing file at a given prior to it being removed\n  # @api private\n  # @raise [Puppet::Error] if the file backup failed\n  # @return [void]\n  def backup_existing\n    unless perform_backup\n      # TRANSLATORS refers to a file which could not be backed up\n      raise Puppet::Error, _(\"Could not back up; will not remove\")\n    end\n  end\n\n  # Make sure the file we wrote out is what we think it is.\n  # @param [Puppet::Parameter] property the param or property that wrote the file, or nil\n  # @param [String] path to the file\n  # @param [String] the checksum for the local file\n  #\n  # @api private\n  #\n  def fail_if_checksum_is_wrong(property, path, content_checksum)\n    desired_checksum = desired_checksum(property, path)\n\n    if desired_checksum && content_checksum != desired_checksum\n      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 }\n    end\n  end\n","sourceCodeStart":1047,"sourceCodeEnd":1083,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/type/file.rb#L1047-L1083","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set `backup => false` on file resources you intentionally replace without backups.","Verify the local bucket: clientbucketdir must exist and be writable by the agent (owned puppet:puppet, mode 0750+).","Verify a remote bucket resolves and is reachable before the next run.","Run `puppet agent -t --debug` to see the underlying perform_backup failure detail."],"exampleFix":"// before: replacing a file while the bucket is broken\nfilebucket { 'main':\n  path   => false,\n  server => 'puppet.example.com',  // unreachable\n}\nfile { '/etc/app.conf':\n  ensure => file,\n  source => 'puppet:///modules/app/app.conf',\n  backup => 'main',\n}\n\n// after: this file does not need a backup\nfile { '/etc/app.conf':\n  ensure => file,\n  source => 'puppet:///modules/app/app.conf',\n  backup => false,\n}","handlingStrategy":"validation","validationCode":"# Ruby pre-flight on the agent side\ndir = Puppet[:clientbucketdir]\nif Puppet[:bucket].nil? && (!Puppet::FileSystem.exist?(dir) || !File.writable?(dir))\n  fail(\"#{dir} missing or not writable — fix the bucket or set backup => false on files you replace\")\nend","typeGuard":null,"tryCatchPattern":"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.","preventionTips":["Set backup => false explicitly for disposable files.","Monitor filebucket server reachability like any other Puppet infrastructure.","Keep clientbucketdir owned by the agent user with mode 0750.","Test bucket changes on one node with puppet agent -t --debug."],"tags":["puppet","file","filebucket","backup","permissions"],"backgroundTag":"file-backup-failure","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}