{"record":{"id":"ed6d27122edf8e11","repo":"fluent/fluentd","slug":"invalid-unique-id","errorCode":null,"errorMessage":"invalid unique_id","messagePattern":"invalid unique_id","errorType":"exception","errorClass":"FileChunkError","httpStatus":null,"severity":"error","filePath":"lib/fluent/plugin/buffer/file_chunk.rb","lineNumber":223,"sourceCode":"        end\n\n        # used only for queued v0.12 buffer path or broken files\n        def self.unique_id_from_path(path)\n          if /\\.(b|q)([0-9a-f]+)\\.[^\\/]*\\Z/n =~ path # //n switch means explicit 'ASCII-8BIT' pattern\n            return $2.scan(/../).map{|x| x.to_i(16) }.pack('C*')\n          end\n          nil\n        end\n\n        def restore_metadata(bindata)\n          data = restore_metadata_with_new_format(bindata)\n\n          unless data\n            # old type of restore\n            data = Fluent::MessagePackFactory.msgpack_unpacker(symbolize_keys: true).feed(bindata).read rescue {}\n          end\n          raise FileChunkError, \"invalid meta data\" if data.nil? || !data.is_a?(Hash)\n          raise FileChunkError, \"invalid unique_id\" unless data[:id]\n          raise FileChunkError, \"invalid created_at\" unless data[:c].to_i > 0\n          raise FileChunkError, \"invalid modified_at\" unless data[:m].to_i > 0\n\n          now = Fluent::Clock.real_now\n\n          @unique_id = data[:id]\n          @size = data[:s] || 0\n          @created_at = data[:c]\n          @modified_at = data[:m]\n\n          @metadata.timekey = data[:timekey]\n          @metadata.tag = data[:tag]\n          @metadata.variables = data[:variables]\n          @metadata.seq = data[:seq] || 0\n        end\n\n        def restore_metadata_partially(chunk)\n          @unique_id = self.class.unique_id_from_path(chunk.path) || @unique_id","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/fluent/fluentd/blob/dd45c6e18dc7be33b5e5a0f0767bf46307ff5626/lib/fluent/plugin/buffer/file_chunk.rb#L205-L241","documentation":"After restoring a .meta payload into a Hash, restore_metadata validates required fields; :id is the chunk's unique_id. An empty Hash (the rescue fallback for unparseable data) or a Hash missing :id raises FileChunkError 'invalid unique_id'. This is the most common manifestation of a corrupt or foreign-format .meta file.","triggerScenarios":"The msgpack fallback produced {} because feed(bindata).read raised (truncated/garbage file), so data[:id] is nil; or the Hash parsed fine but genuinely lacks the id key (e.g. a .meta written by different software or a hand-crafted file).","commonSituations":"Power loss truncating .meta files; partial writes from a full disk; mixing buffer directories from different fluentd major versions; restoring from an inconsistent filesystem snapshot.","solutions":["Accept fluentd's automatic quarantine/deletion of the broken chunk on resume (data in that chunk is lost) — check logs for 'staged meta file is broken. invalid unique_id'","Restore the buffer directory from a known-good backup if the data is valuable","Address the root cause: avoid SIGKILL, monitor disk space, use a journaling filesystem","If it recurs across many files, suspect hardware or a version downgrade and inspect the .meta bytes (msgpack) of one file"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"Dir.glob('buffer/**/*.meta').each do |m|\n  data = Fluent::MessagePackFactory.msgpack_unpacker(symbolize_keys: true)\n                .feed(File.binread(m)).read rescue nil\n  warn \"#{m}: missing unique_id\" unless data.is_a?(Hash) && data[:id]\nend","typeGuard":null,"tryCatchPattern":"begin\n  stage, queue = buffer.resume\nrescue Fluent::Plugin::Buffer::FileChunkError => e\n  # per-file failures are already caught inside resume; catching here guards whole-dir failures\n  log.fatal \"buffer resume failed: #{e.message}\"\n  exit!\nend","preventionTips":["Graceful shutdowns; disk space alerts","Keep buffer dirs on journaling local filesystems, not NFS","Test disaster recovery by killing fluentd under load in staging","Backup buffer directories; a missing :id means the chunk is unrecoverable by design"],"tags":["fluentd","buffer","file-chunk","corruption","resume","unique-id"],"backgroundTag":"corrupt-buffer-metadata","analyzedSha":"dd45c6e18dc7be33b5e5a0f0767bf46307ff5626","analyzedAt":"2026-08-21T16:22:07.332Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}