vectordotdev/vector · error · ChunkedGelfDecoderError

Received chunk with message id {message_id} and sequence num

Error message

Received chunk with message id {message_id} and sequence number {sequence_number} has a sequence number greater than its total chunks value of {total_chunks}

What it means

Each GELF chunk carries a sequence number that indexes it within its message, so it must be strictly less than the message's total-chunks value. When `sequence_number >= total_chunks`, the decoder rejects the chunk with `InvalidSequenceNumberSnafu` because there is no valid slot to store it in. Like the other chunk-header checks, this is a per-datagram error propagated through the framing `Result`, not a panic.

Source

Thrown at lib/codecs/src/decoding/framing/chunked_gelf.rs:361

        ensure!(
            chunk.remaining() >= 10,
            InvalidChunkHeaderSnafu { header: chunk }
        );

        let message_id = chunk.get_u64();
        let sequence_number = chunk.get_u8();
        let total_chunks = chunk.get_u8();

        ensure!(
            total_chunks > 0 && total_chunks <= GELF_MAX_TOTAL_CHUNKS,
            InvalidTotalChunksSnafu {
                message_id,
                sequence_number,
                total_chunks
            }
        );

        ensure!(
            sequence_number < total_chunks,
            InvalidSequenceNumberSnafu {
                message_id,
                sequence_number,
                total_chunks
            }
        );

        let mut state_lock = self.state.lock().expect("poisoned lock");

        // Only a new message grows the table, so the limit applies on insert. Checking it
        // before the lookup rejected chunks of messages already pending, which could then
        // never complete and expired instead.
        if !state_lock.contains_key(&message_id)
            && let Some(pending_messages_limit) = self.pending_messages_limit
        {
            ensure!(
                state_lock.len() < pending_messages_limit,

View on GitHub (pinned to 99894c8d88)

Solutions

Fix the sender to use 0-based sequence numbers strictly less than the chunk count (`seq` in `0..total`).
Hex-dump a failing datagram (bytes 9 and 10 after the magic) to see which field is wrong before changing code.
Move non-GELF producers off the GELF UDP port.

Defensive patterns

Strategy: try-catch

Try / catch

Err(e) if e.to_string().contains("sequence number greater than") => {
    debug!(error = %e, "discarding chunk with out-of-range sequence");
}

Prevention

Use 0-based sequence numbers in custom GELF chunkers; add a property test asserting seq < total.
Fuzz custom senders with the same decoder the receiver uses before shipping.

When it happens

Trigger: A chunked datagram where the seq byte is ≥ the total byte — e.g. seq 3 of total 3, total encoded as 0 by an off-by-one sender, or non-GELF binary matching the magic prefix.

Common situations: Hand-written GELF chunkers with off-by-one errors (using 1-based sequence numbers instead of 0-based, or writing `count` instead of `count-1`); protocol scanners; corrupted UDP payloads.

Related errors

AI-assisted analysis of vectordotdev/vector@99894c8d88 (2026-08-20). Data as JSON: /api/errors/fa95369a0d62dcf9. Report an issue: GitHub.