Pumpkin-MC/Pumpkin · error · PacketEncodeError

Packet exceeds maximum length

Error message

Packet exceeds maximum length: {0}

What it means

`PacketEncodeError::TooLong` is returned when a serialized packet exceeds the protocol's maximum packet length (the largest length the length-prefix VarInt/frame allows). The payload size is carried in the variant so the caller can log it. Encoding is aborted before writing to the network.

Solutions

1. Enable/configure compression so large payloads fit under the frame limit.
2. Split the payload into multiple smaller packets (e.g. chunk sections separately).
3. Log the reported size and compare against the protocol's max packet length to see how far over the limit you are.
4. Trim the packet contents (e.g. reduce entity metadata or NBT size).

const MAX_PACKET_LEN: usize = 2_097_151; // 3-byte VarInt max
if encoded.len() > MAX_PACKET_LEN {
    return Err(PacketEncodeError::TooLong(encoded.len()));
}

match write_packet(&packet, version, &mut out) {
    Ok(()) => {},
    Err(PacketEncodeError::TooLong(n)) => {
        log::error!("packet too large ({n} bytes); splitting payload");
    }
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: Encoding a packet whose serialized buffer (before or after compression) is larger than the maximum allowed frame size — e.g. a huge chunk update, a giant chat/NBT payload, or an uncompressed packet that should have been compressed.

Common situations: Sending enormous world data or NBT blobs in one packet; compression disabled so a payload that would fit compressed exceeds the raw limit; a plugin building an oversized payload.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• Writing packet failed
• IO error
• JSON error
• Authentication servers are down
• Texture Error

AI-assisted analysis of Pumpkin-MC/Pumpkin@8d4639e25a (2026-09-09). Data as JSON: /api/errors/df724b616faa8839. Report an issue: GitHub.

Appendix: source

Thrown at crates/pumpkin-protocol/src/lib.rs:291

    fn read(read: &mut &'a [u8], version: &JavaMinecraftVersion) -> Result<Self, ReadingError>;
}

pub trait BClientPacket: Packet {
    fn write_packet(&self, writer: impl Write) -> Result<(), Error>;

    fn serialize_packet(&self) -> Result<Bytes, Error> {
        crate::bedrock::packet_encoder::serialize_packet(self)
    }
}

pub trait BServerPacket: Packet + Sized {
    fn read(read: impl Read) -> Result<Self, Error>;
}

/// Errors that can occur during packet encoding.
#[derive(Error, Debug)]
pub enum PacketEncodeError {
    #[error("Packet exceeds maximum length: {0}")]
    TooLong(usize),
    #[error("Compression failed {0}")]
    CompressionFailed(String),
    #[error("Writing packet failed: {0}")]
    Message(String),
}

#[derive(Error, Debug)]
pub enum PacketDecodeError {
    #[error("failed to decode packet ID")]
    DecodeID,
    #[error("packet exceeds maximum length")]
    TooLong,
    #[error("packet length is out of bounds")]
    OutOfBounds,
    #[error("malformed packet length VarInt: {0}")]
    MalformedLength(String),
    #[error("failed to decompress packet: {0}")]

View on GitHub (pinned to 8d4639e25a)