{"record":{"id":"0c7f826ead451633","repo":"puppetlabs/puppet","slug":"could-not-rename-corrupt-filename-remove-manua","errorCode":null,"errorMessage":"Could not rename corrupt %{filename}; remove manually","messagePattern":"Could not rename corrupt %(.+?); remove manually","errorType":"exception","errorClass":"Puppet::Error","httpStatus":null,"severity":"error","filePath":"lib/puppet/util/storage.rb","lineNumber":65,"sourceCode":"    filename = Puppet[:statefile]\n\n    unless Puppet::FileSystem.exist?(filename)\n      init if @@state.nil?\n      return\n    end\n    unless File.file?(filename)\n      Puppet.warning(_(\"Checksumfile %{filename} is not a file, ignoring\") % { filename: filename })\n      return\n    end\n    Puppet::Util.benchmark(:debug, \"Loaded state in %{seconds} seconds\") do\n      @@state = Puppet::Util::Yaml.safe_load_file(filename, [Symbol, Time])\n    rescue Puppet::Util::Yaml::YamlLoadError => detail\n      Puppet.err _(\"Checksumfile %{filename} is corrupt (%{detail}); replacing\") % { filename: filename, detail: detail }\n\n      begin\n        File.rename(filename, filename + \".bad\")\n      rescue\n        raise Puppet::Error, _(\"Could not rename corrupt %{filename}; remove manually\") % { filename: filename }, detail.backtrace\n      end\n    end\n\n    unless @@state.is_a?(Hash)\n      Puppet.err _(\"State got corrupted\")\n      init\n    end\n  end\n\n  def self.stateinspect\n    @@state.inspect\n  end\n\n  def self.store\n    Puppet.debug \"Storing state\"\n\n    Puppet.info _(\"Creating state file %{file}\") % { file: Puppet[:statefile] } unless Puppet::FileSystem.exist?(Puppet[:statefile])\n","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/puppetlabs/puppet/blob/e227c27540975c25aa22d533a52424a9d2fc886a/lib/puppet/util/storage.rb#L47-L83","documentation":"Puppet::Util::Storage.load (storage.rb:65) safe_loads the agent state file (class checksumfile, default $vardir/state/state.yaml). On Puppet::Util::Yaml::YamlLoadError it logs 'Checksumfile ... is corrupt; replacing' and tries File.rename(filename, filename + '.bad'). If THAT rename raises (EACCES/EROFS/EPERM, wrong user, or '.bad' destination conflicts, notably on Windows where rename onto an existing file fails), it raises Puppet::Error 'Could not rename corrupt <file>; remove manually' chained with the original load error's backtrace.","triggerScenarios":"state.yaml corrupted (crash mid-write, disk full) AND the puppet process lacking permission to rename it: agent run as non-root over a root-owned cache dir; /var/lib/puppet on a read-only mount; a leftover state.yaml.bad blocking the rename on Windows.","commonSituations":"Mixing root and non-root puppet runs on the same $vardir; unclean shutdown during catalog application; restricted containers with read-only /var; restored backups that changed file ownership.","solutions":["Manually move the file aside as an admin: mv /opt/puppetlabs/puppet/cache/state/state.yaml /tmp/ (or /var/lib/puppet/state/state.yaml on older layouts); puppet rebuilds it.","Fix ownership/permissions of the state directory so the puppet service user can write (chown -R puppet:puppet $vardir).","Stop mixing root and non-root runs against the same vardir; pin the agent to one user via systemd/launchd config.","If on a read-only mount, relocate $vardir (puppet config set vardir) to writable storage."],"exampleFix":"// before\n# agent run fails: Could not rename corrupt /var/lib/puppet/state/state.yaml; remove manually\n\n// after (remediation shell)\n// systemctl stop puppet\n// mv /var/lib/puppet/state/state.yaml{,.manual-bak}\n// chown -R puppet:puppet /var/lib/puppet\n// systemctl start puppet","handlingStrategy":"try-catch","validationCode":"f = Puppet::Util::Storage.checksumfile\nif File.exist?(f) && !(File.readable?(f) && File.writable?(File.dirname(f)))\n  raise Puppet::Error, \"cannot manage corrupt state file #{f}: fix ownership first\"\nend","typeGuard":null,"tryCatchPattern":"begin\n  Puppet::Util::Storage.load\nrescue Puppet::Error => e\n  raise unless e.message.include?('remove manually')\n  FileUtils.mv(Puppet::Util::Storage.checksumfile, Puppet::Util::Storage.checksumfile + '.manual') rescue nil\n  Puppet::Util::Storage.load # one remediated retry; state rebuilds from scratch\nend","preventionTips":["Run the agent under one dedicated user; never alternate root and non-root against the same vardir.","Monitor for state.yaml corruption after crashes/disk-full events and quarantine the file proactively.","Keep $vardir on writable storage with correct ownership (chown -R puppet:puppet)."],"tags":["puppet","state-file","yaml","corruption","filesystem-permissions"],"backgroundTag":"corrupt-state-file","analyzedSha":"e227c27540975c25aa22d533a52424a9d2fc886a","analyzedAt":"2026-08-21T20:49:46.650Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}