can1357/oh-my-pi · error · RpcError

RPC chunk payload exceeds the transport limit

Error message

RPC chunk payload exceeds the transport limit

What it means

The individual chunk's decoded payload is larger than _RPC_CHUNK_PAYLOAD_BYTES, the maximum bytes a single chunk may carry. Even though the base64 string was valid, the sender packed more payload per chunk than the transport allows. The limit exists so no single frame exceeds transport frame-size constraints after base64 encoding.

Source

Thrown at python/omp-rpc/src/omp_rpc/client.py:184

            or isinstance(byte_length, bool)
            or index < 0
            or count < 2
            or count > max_chunk_count
            or index >= count
            or byte_length < _MAX_RPC_FRAME_BYTES
            or byte_length > _MAX_RPC_REASSEMBLED_BYTES
            or not isinstance(data, str)
            or not data
        ):
            raise RpcError("Invalid RPC chunk metadata")
        try:
            chunk = base64.b64decode(data, validate=True)
        except (binascii.Error, ValueError) as exc:
            raise RpcError("Invalid RPC chunk data") from exc
        if base64.b64encode(chunk).decode("ascii") != data:
            raise RpcError("Invalid RPC chunk data")
        if len(chunk) > _RPC_CHUNK_PAYLOAD_BYTES:
            raise RpcError("RPC chunk payload exceeds the transport limit")

        if self._pending is None:
            if index != 0:
                raise RpcError("RPC chunk sequence must start at index 0")
            self._pending = _PendingRpcChunks(chunk_id, count, byte_length)
        pending = self._pending
        if (
            pending.chunk_id != chunk_id
            or pending.count != count
            or pending.byte_length != byte_length
            or pending.next_index != index
        ):
            raise RpcError("RPC chunk sequence mismatch")
        pending.chunks.append(chunk)
        pending.received_bytes += len(chunk)
        pending.next_index += 1
        if pending.received_bytes > pending.byte_length:
            raise RpcError("RPC chunk sequence exceeds its declared length")

View on GitHub (pinned to 9690622007)

Solutions

  1. Re-chunk on the sender using the same limit the client enforces (_RPC_CHUNK_PAYLOAD_BYTES decoded bytes per chunk).
  2. Align both endpoints to the same omp-rpc version so chunk-size limits match.
  3. If you control chunking, size chunks conservatively (e.g. under the limit by a margin) and split by decoded byte length, not base64 string length.
  4. Catch RpcError, log len(data)//4*3 as an estimate of payload size, and adjust the sender's chunk size accordingly.

Example fix

// before
CHUNK = 1_000_000  # too big for client transport
for i in range(0, len(payload), CHUNK):
    send_chunk(payload[i:i+CHUNK])

// after
CHUNK = _RPC_CHUNK_PAYLOAD_BYTES  # match the client's transport limit
for i in range(0, len(payload), CHUNK):
    send_chunk(payload[i:i+CHUNK])
Defensive patterns

Strategy: validation

Validate before calling

def chunk_payload(payload: bytes, limit: int) -> list[bytes]:
    if limit <= 0:
        raise ValueError("limit must be positive")
    return [payload[i:i + limit] for i in range(0, len(payload), limit)] or [b""]
# call with limit equal to the client's _RPC_CHUNK_PAYLOAD_BYTES

Type guard

def within_transport_limit(chunk: bytes, limit: int) -> bool:
    return len(chunk) <= limit

Try / catch

try:
    client.push(frame)
except RpcError as exc:
    if "transport limit" in str(exc):
        logger.error("chunk too large (%d bytes); re-chunk smaller", len(frame.get("data", "")) * 3 // 4)
        rechunk_and_resend(smaller_limit)
    else:
        raise

Prevention

When it happens

Trigger: push() of an rpc_chunk whose data decodes to more than _RPC_CHUNK_PAYLOAD_BYTES bytes — e.g. the sender used a larger chunk size than the client's compile-time transport limit.

Common situations: Sender and receiver configured with different max-frame sizes (sender raised its chunk size, client didn't); a sender that chunks by character count of the base64 string instead of decoded byte count; protocol version mismatch where limits changed between releases.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/7f479f2f1d410cc1. Report an issue: GitHub.