sgl-project/sglang · error · AssertionError

Unhandled known MessagePack extension code: {code}

Error message

Unhandled known MessagePack extension code: {code}

What it means

msgpack_utils registers known extension codes (buffers, shm pointers, CUDA IPC tensor proxies). ext_hook decodes each by code; reaching the raise means the packed data carries a code that matches a known code constant on the receiver but has no decode branch — i.e., malformed or version-skewed wire data.

Source

Thrown at python/sglang/srt/utils/msgpack_utils.py:248

    if code == _MSGPACK_EXT_ARRAY:
        typecode, raw_data = _unpack_buffer_ext(data)
        res = array(typecode)
        res.frombytes(raw_data)
        return res
    if code == _MSGPACK_EXT_TORCH_TENSOR:
        metadata, raw_data = _unpack_buffer_ext(data)
        shape, dtype, device = metadata
        return _restore_torch_tensor(shape, dtype, raw_data, device)
    if code == _MSGPACK_EXT_NP_ARRAY:
        metadata, raw_data = _unpack_buffer_ext(data)
        shape, dtype = metadata
        return np.frombuffer(raw_data, dtype=np.dtype(dtype)).copy().reshape(shape)
    if code == _MSGPACK_EXT_SHM_POINTER_MM_DATA:
        return _decode_shm_pointer_mm_data(_unpack_ext(data))
    if code == _MSGPACK_EXT_CUDA_IPC_TENSOR_PROXY:
        return _decode_cuda_ipc_tensor_proxy(_unpack_ext(data))
    raise AssertionError(f"Unhandled known MessagePack extension code: {code}")

View on GitHub (pinned to 0132848349)

Solutions

1. Restart all sglang processes from the same installed version so encoder and decoder share ext code tables.
2. For malformed input, validate/corrupt-test with the dedicated rejection path rather than expecting graceful decode.
3. If adding a new ext code, remember to add both the ext_hook branch and decoder.

try:
    obj = msgpack.unpackb(data, ext_hook=ext_hook)
except AssertionError as e:
    raise ValueError("corrupted or version-skewed IPC payload") from e

When it happens

Trigger: Unpacking bytes whose ext code equals one of the module's known codes but none of the if-branches handled it, typically from truncated/corrupted payloads or sender/receiver built from different sglang versions.

Common situations: Mixed-version processes on the same ZMQ/IPC channel after a partial upgrade; tests feeding hand-crafted malformed ext payloads (the test_malformed_known_buffer_ext_is_rejected caller).

Related errors

• Cannot msgpack decode object of type {type(obj)} as {tp} wit
• Unsupported dtype: {obj.dtype}
• Cannot msgpack encode object of type {type(obj)} with enc_ho
• Serve backend {name!r} uses API version {backend.api_version
• scalar_type_id {scalar_type_id} doesn't exists.

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/df0d976ee1074186. Report an issue: GitHub.