vectordotdev/vector · error · ChunkedGelfDecoderError::InvalidSequenceNumber

Received chunk with message id

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

GELF chunk sequence numbers are 0-indexed, so every chunk must satisfy `sequence_number < total_chunks`. When a chunk arrives whose sequence number is greater than or equal to the declared total (e.g. sequence 5 of a 4-chunk message), `decode_chunk` rejects it with this error identifying the message id and both values. Such a chunk cannot belong to a coherent message reassembly.

Solutions

1. Fix the sender to number chunks 0-based: first chunk has sequence 0, last has sequence total-1.
2. Ensure the sender's declared total in byte 9 matches the actual number of chunks it transmits.
3. Use the message id from the error to locate the offending producer and inspect its chunking loop for off-by-one errors.

Example fix

// before: 1-based sequence numbers
for (i, part) in parts.iter().enumerate() {
    chunk[8] = (i + 1) as u8; // last seq == total -> error
}

// after: 0-based per GELF spec
for (i, part) in parts.iter().enumerate() {
    chunk[8] = i as u8; // 0..total-1
}

// sender-side guard
for (i, part) in parts.iter().enumerate() {
    assert!(i < total as usize, "sequence must be 0-based and < total");
    chunk[8] = i as u8;
    chunk[9] = total as u8;
    send(chunk_header_with(part));
}

match framing.decode(&datagram) {
    Err(e) if e.to_string().contains("sequence number greater than") => {
        error!("sender uses 1-based sequence numbers or miscounted chunks: {e}");
    }
    other => { /* handle normally */ }
}

When it happens

Trigger: A datagram passes header length and total-chunks validation, but its sequence-number byte is >= the total-chunks byte — produced by senders numbering chunks from 1 instead of 0, or emitting more chunks than declared.

Common situations: A custom GELF client implementing 1-based sequence numbering against receivers expecting 0-based; a sender that splits the payload into more chunks than it wrote into the header; packet duplication/corruption altering header bytes.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Invalid chunk header with less than 10 bytes: 0x
• Received chunk with message id
• Buffered payload limit of
• Pending messages limit of
• Received chunk with message id

AI-assisted analysis of vectordotdev/vector@bdb87aeaa4 (2026-09-16). Data as JSON: /api/errors/fa95369a0d62dcf9. Report an issue: GitHub.

Appendix: source

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

        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 chunk_len = chunk.len();

        // A lone chunk is already complete, but it cannot reuse the ID of a pending message.
        if total_chunks == 1 {
            if chunk_len > self.max_length {
                return Err(ChunkedGelfDecoderError::MaxLengthExceed {
                    message_id,
                    sequence_number,
                    length: chunk_len,
                    max_length: self.max_length,

View on GitHub (pinned to bdb87aeaa4)