{"record":{"id":"53d1f46ffd643b96","repo":"fluent/fluentd","slug":"enqueued-meta-file-is-broken-e-message","errorCode":null,"errorMessage":"enqueued meta file is broken. #{e.message}","messagePattern":"enqueued meta file is broken\\. #(.+?)","errorType":"exception","errorClass":"FileChunkError","httpStatus":null,"severity":"critical","filePath":"lib/fluent/plugin/buffer/file_chunk.rb","lineNumber":390,"sourceCode":"\n        def load_existing_enqueued_chunk(path)\n          @path = path\n          raise FileChunkError, \"enqueued file chunk is empty\" if File.size(@path).zero?\n\n          @chunk = File.open(@path, 'rb')\n          @chunk.set_encoding(Encoding::ASCII_8BIT)\n          @chunk.binmode\n          @chunk.seek(0, IO::SEEK_SET)\n          @bytesize = @chunk.size\n          @commit_position = @chunk.size\n\n          @meta_path = @path + '.meta'\n          if File.readable?(@meta_path)\n            begin\n              restore_metadata(File.open(@meta_path){|f| f.set_encoding(Encoding::ASCII_8BIT); f.binmode; f.read })\n            rescue => e\n              @chunk.close\n              raise FileChunkError, \"enqueued meta file is broken. #{e.message}\"\n            end\n          else\n            restore_metadata_partially(@chunk)\n          end\n          @state = :queued\n        end\n\n        private\n\n        def restore_metadata_with_new_format(chunk)\n          if chunk.size <= 6 # size of BUFFER_HEADER (2) + size of data size(4)\n            return nil\n          end\n\n          if chunk.slice(0, 2) == BUFFER_HEADER\n            size = chunk.slice(2, 4).unpack1('N')\n            if size\n              return Fluent::MessagePackFactory.msgpack_unpacker(symbolize_keys: true).feed(chunk.slice(6, size)).read rescue nil","sourceCodeStart":372,"sourceCodeEnd":408,"githubUrl":"https://github.com/fluent/fluentd/blob/dd45c6e18dc7be33b5e5a0f0767bf46307ff5626/lib/fluent/plugin/buffer/file_chunk.rb#L372-L408","documentation":"When loading an existing enqueued chunk, the classic file buffer reads the companion .meta (only if it exists and is readable) and runs restore_metadata on its bytes; any parse failure (truncated content, msgpack error, 'invalid meta data'/'invalid unique_id'/'invalid created_at' from the field checks) is re-raised as FileChunkError 'enqueued meta file is broken. <original message>'. Note the asymmetry: a missing or unreadable .meta is fine (restore_metadata_partially recovers the chunk from the data file alone); only a present-but-unparseable .meta raises.","triggerScenarios":"A readable q<hex>.buf.meta that fails restore_metadata: truncated by crash mid-write, corrupted bytes, or written by an incompatible fluentd version, next to an otherwise valid q<hex>.buf data file.","commonSituations":"Crash/power loss right after the chunk data was flushed but while meta was being rewritten; version upgrades with leftover queued chunks; disk-full conditions; manual edits to buffer files.","solutions":["Rename or delete only the broken .meta file: without it the queued chunk is still delivered via restore_metadata_partially (time/tag metadata is lost but the events ship), then restart fluentd.","If the data file itself is also suspect (empty/garbage), quarantine both files instead.","Fix the durability root cause: ensure the buffer partition has space, use graceful shutdown, and avoid version jumps with non-empty buffers."],"exampleFix":"# before: 'enqueued meta file is broken. invalid meta data' blocks startup\n# after: drop only the meta, keep the data chunk deliverable\nsudo systemctl stop fluentd\nmv /var/log/fluent/buffer/q3ab9....buf.meta /var/backups/fluent-broken/\nsudo systemctl start fluentd","handlingStrategy":"validation","validationCode":"# preflight: queued chunks without meta are OK; broken meta files are the risk\nBUFFER_DIR = '/var/log/fluent/buffer'\nDir.glob(\"#{BUFFER_DIR}/q*.buf.meta\").each do |meta|\n  warn \"suspicious meta (too small): #{meta}\" if File.size(meta) < 16\nend","typeGuard":null,"tryCatchPattern":"begin\n  chunk = Fluent::Plugin::Buffer::FileChunk.new(metadata, path, :queued)\nrescue Fluent::Plugin::Buffer::FileChunkError => e\n  # dropping just the meta lets restore_metadata_partially ship the data\n  log.warn \"dropping broken meta for #{path}: #{e.message}\"\n  File.rename(\"#{path}.meta\", \"#{path}.meta.broken\") rescue nil\n  retry\nend","preventionTips":["Prefer graceful restarts so meta files are never mid-write.","Alert on buffer disk usage; short writes under ENOSPC corrupt meta.","Upgrade fluentd only with an empty/drained buffer.","Do not hand-edit files inside the buffer directory."],"tags":["fluentd","ruby","file-buffer","metadata-corruption","startup-failure"],"backgroundTag":"buffer-metadata-corruption","analyzedSha":"dd45c6e18dc7be33b5e5a0f0767bf46307ff5626","analyzedAt":"2026-08-21T16:22:07.332Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}