docling-project/docling · error · RuntimeError

Invalid BYTES data: insufficient bytes for string of length

Error message

Invalid BYTES data: insufficient bytes for string of length {str_len} at offset {offset}

What it means

Raised while decoding a KServe v2 BYTES-tensor response payload. The decoder reads a 4-byte little-endian length prefix per string, then expects that many bytes to follow; if the remaining buffer is shorter than the declared string length, the payload is truncated or malformed. This indicates the remote server returned a corrupted or non-conforming BYTES tensor, or the response shape does not match a length-prefixed BYTES encoding.

Source

Thrown at docling/models/inference_engines/common/kserve_v2_utils.py:42

    for value in tensor.reshape(-1):
        encoded = encode_bytes_element(value)
        chunks.append(len(encoded).to_bytes(4, byteorder="little"))
        chunks.append(encoded)
    return b"".join(chunks)


def decode_bytes_tensor(raw_output: bytes, shape: tuple[int, ...]) -> np.ndarray:
    """Decode a length-prefixed BYTES payload to a numpy object array."""
    strings, offset = [], 0
    for _ in range(int(np.prod(shape))):
        if offset + 4 > len(raw_output):
            raise RuntimeError(
                f"Invalid BYTES data: insufficient bytes for length prefix at offset {offset}"
            )
        str_len = int.from_bytes(raw_output[offset : offset + 4], byteorder="little")
        offset += 4
        if offset + str_len > len(raw_output):
            raise RuntimeError(
                f"Invalid BYTES data: insufficient bytes for string of length {str_len} at offset {offset}"
            )
        strings.append(raw_output[offset : offset + str_len])
        offset += str_len
    return np.array(strings, dtype=object).reshape(shape)

View on GitHub (pinned to 61d76f1ff3)

Solutions

Verify the server actually returns KServe v2 conforming BYTES tensors (each element prefixed by a 4-byte little-endian length); test with a known-good KServe example model.
Check that the output tensor shape declared in model metadata matches the number of length-prefixed strings actually serialized in the payload.
Capture raw_output bytes and len(raw_output) at the failure offset to confirm whether the payload is truncated (transport issue) vs. mis-encoded (server issue).
If the server cannot be fixed, avoid the BYTES path and request a numeric (FP32/INT64) output instead, decoding it locally.

Example fix

// before: server packs raw concatenated strings
buf = b''.join(strings)  # no length prefixes

// after: KServe v2 conforming BYTES encoding
import struct
buf = b''.join(struct.pack('<I', len(s)) + s for s in strings)

Defensive patterns

Strategy: validation

Validate before calling

def validate_bytes_payload(raw: bytes, shape: tuple[int, ...]) -> None:
    offset, count = 0, int(np.prod(shape))
    for i in range(count):
        if offset + 4 > len(raw):
            raise ValueError(f"truncated length prefix at element {i}")
        n = int.from_bytes(raw[offset:offset + 4], "little")
        offset += 4
        if offset + n > len(raw):
            raise ValueError(f"truncated string at element {i} (need {n} bytes)")
        offset += n

Try / catch

try:
    arr = decode_bytes_tensor(raw_output, shape)
except RuntimeError as e:
    if "Invalid BYTES data" in str(e):
        log.error("server returned malformed BYTES tensor: %s", e)
        raise  # server-side defect; retrying unchanged payload won't help

Prevention

Smoke-test the server with a single tiny request and validate the BYTES payload before running production batches.
Pin the server version so serialization behavior cannot silently change.
Prefer numeric (FP32) outputs over BYTES where the model allows it.

When it happens

Trigger: Calling an inference endpoint whose output datatype is BYTES (via KserveV2Client.infer and decode_bytes_tensor) where the raw output bytes are shorter than sum(4 + str_len) implied by the tensor shape. Happens with shape/byte-count mismatch, partial gRPC/HTTP response, or a server that serializes BYTES without the KServe length-prefix convention.

Common situations: Deploying a custom KServe v2 model that returns strings in a non-standard encoding; mismatch between declared output shape and actual payload; network proxies truncating responses; server version change altering the serialization format.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/45f122e81a2e8b1b. Report an issue: GitHub.