{"record":{"id":"342fd077993ca0f1","repo":"fluent/fluentd","slug":"enqueued-file-chunk-is-empty","errorCode":null,"errorMessage":"enqueued file chunk is empty","messagePattern":"enqueued file chunk is empty","errorType":"exception","errorClass":"FileChunkError","httpStatus":null,"severity":"critical","filePath":"lib/fluent/plugin/buffer/file_chunk.rb","lineNumber":375,"sourceCode":"          else\n            # classic buffer chunk - read only chunk\n            @chunk = File.open(@path, 'rb')\n            @chunk.set_encoding(Encoding::ASCII_8BIT)\n            @chunk.binmode\n            @chunk.seek(0, IO::SEEK_SET)\n            @state = :queued\n            @bytesize = @chunk.size\n\n            restore_metadata_partially(@chunk)\n\n            @commit_position = @chunk.size\n            @unique_id = self.class.unique_id_from_path(@path) || @unique_id\n          end\n        end\n\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)","sourceCodeStart":357,"sourceCodeEnd":393,"githubUrl":"https://github.com/fluent/fluentd/blob/dd45c6e18dc7be33b5e5a0f0767bf46307ff5626/lib/fluent/plugin/buffer/file_chunk.rb#L357-L393","documentation":"While restoring the queue at startup, the classic file buffer plugin loads each already-enqueued chunk (q<hex>.buf) via FileChunk#load_existing_enqueued_chunk. An enqueued chunk is expected to contain committed data; if File.size(path) is zero the constructor raises FileChunkError 'enqueued file chunk is empty'. The error stops fluentd from starting because the buffer plugin cannot reconstruct a consistent state.","triggerScenarios":"A q<hex>.buf file of 0 bytes exists in the buffer directory: the chunk was renamed to queued state but its data write never completed (crash between enqueue and flush), a disk-full short write, manual truncation, or a half-copied buffer directory.","commonSituations":"Hard crashes or OOM kills during enqueue/flush; buffer filesystem that ran out of space or went read-only; rsync/scp of a live buffer directory; leftover files after experiments with buffer path settings.","solutions":["Stop fluentd and delete or quarantine the zero-byte q<hex>.buf file (and its sibling .meta if present) named in the startup error, then restart.","Investigate why the file was created empty: check disk space, dmesg for OOM/FS errors, and whether another process wrote into the buffer dir.","If it recurs, check filesystem health (fsck) and move the buffer to a dedicated, monitored partition."],"exampleFix":"# before: fluentd fails to start on 'enqueued file chunk is empty'\n# after: remove the empty queued chunk and restart\nsudo systemctl stop fluentd\nfind /var/log/fluent/buffer -name 'q*.buf' -size 0 -print -delete\nsudo systemctl start fluentd","handlingStrategy":"validation","validationCode":"# preflight: flag zero-size queued chunk files before startup\nBUFFER_DIR = '/var/log/fluent/buffer'\nDir.glob(\"#{BUFFER_DIR}/*\").each do |f|\n  next if f.end_with?('.meta')\n  warn \"empty chunk file: #{f}\" if File.size(f).zero?\nend","typeGuard":null,"tryCatchPattern":"begin\n  chunk = Fluent::Plugin::Buffer::FileChunk.new(metadata, path, :queued)\nrescue Fluent::Plugin::Buffer::FileChunkError => e\n  log.error \"removing empty queued chunk #{path}: #{e.message}\"\n  File.delete(path) if File.size(path).zero?\nend","preventionTips":["Use graceful shutdowns so chunks are fully written before rename.","Keep the buffer filesystem healthy and non-full (monitoring + alerts).","Never copy a buffer directory while fluentd is writing to it.","Run a pre-start check for zero-size files in the buffer dir."],"tags":["fluentd","ruby","file-buffer","empty-file","startup-failure"],"backgroundTag":"empty-buffer-chunk-file","analyzedSha":"dd45c6e18dc7be33b5e5a0f0767bf46307ff5626","analyzedAt":"2026-08-21T16:22:07.332Z","schemaVersion":2},"datasetVersion":"2026-08-21T18:17:14.833Z"}