fluent/fluentd · critical · FileChunkError

enqueued file chunk is empty

Error message

enqueued file chunk is empty

What it means

The single-file buffer plugin re-opens already-enqueued chunks at startup via FileSingleChunk#load_existing_enqueued_chunk. An enqueued chunk holds committed data awaiting flush; if File.size(path) is zero it raises FileChunkError 'enqueued file chunk is empty' and fluentd startup aborts.

Source

Thrown at lib/fluent/plugin/buffer/file_single_chunk.rb:294

          @chunk = File.open(@path, 'rb+')
          @chunk.set_encoding(Encoding::ASCII_8BIT)
          @chunk.sync = true
          @chunk.binmode
          @chunk.seek(0, IO::SEEK_END)

          restore_metadata

          @state = :staged
          @bytesize = @chunk.size
          @commit_position = @chunk.pos
          @adding_bytes = 0
          @adding_size = 0
        end

        def load_existing_enqueued_chunk(path)
          @path = path
          raise FileChunkError, "enqueued file chunk is empty" if File.size(@path).zero?

          @chunk = File.open(@path, 'rb')
          @chunk.set_encoding(Encoding::ASCII_8BIT)
          @chunk.binmode
          @chunk.seek(0, IO::SEEK_SET)

          restore_metadata

          @state = :queued
          @bytesize = @chunk.size
          @commit_position = @chunk.size
        end
      end
    end
  end
end

View on GitHub (pinned to dd45c6e18d)

Solutions

1. Stop fluentd, remove or quarantine the zero-byte queued chunk file reported at startup, restart.
2. Diagnose the write failure (disk space, dmesg/OOM, concurrent writers) so it does not recur.
3. If multiple files are affected, consider draining to a fresh buffer directory rather than deleting piecemeal.

Example fix

# before: startup fails on 'enqueued file chunk is empty'
# after: remove empty queued chunks and restart
sudo systemctl stop fluentd
find /var/log/fluent/buffer -name '*q*.buf*' -size 0 -print -delete
sudo systemctl start fluentd

# preflight: zero-size enqueued chunk files (single-mode buffer)
Dir.glob('/var/log/fluent/buffer/*q*.buf*').each do |f|
  warn "empty queued chunk: #{f}" if File.size(f).zero?
end

begin
  chunk = Fluent::Plugin::Buffer::FileSingleChunk.new(metadata, path, :queued, key)
rescue Fluent::Plugin::Buffer::FileChunkError => e
  log.error "removing empty queued chunk #{path}: #{e.message}"
  File.delete(path) if File.size(path).zero?
end

When it happens

Trigger: A queued chunk file (name containing .q<hex>.) of 0 bytes: the enqueue rename completed but no data was ever written, a crash or disk-full interrupted the write, or the file was truncated externally.

Common situations: Hard crashes during enqueue; full or read-only buffer partition; incomplete copies of buffer directories; leftover files after changing the buffer path configuration.

Related errors

• enqueued file chunk is empty
• staged file chunk is empty
• staged meta file is broken. #{e.message}
• enqueued meta file is broken. #{e.message}
• Invalid chunk found. unique_id and key not exist: #{@path}

AI-assisted analysis of fluent/fluentd@dd45c6e18d (2026-08-21). Data as JSON: /api/errors/f88b7b52ec7c9cff. Report an issue: GitHub.