{"record":{"id":"dd6b32a501509889","repo":"cocoindex-io/cocoindex","slug":"unknown-routing-byte-routing-byte-x-error-c","errorCode":null,"errorMessage":"Unknown routing byte: {routing_byte:#x} ({_error_context()})","messagePattern":"Unknown routing byte: (.+?) \\((.+?)\\)","errorType":"exception","errorClass":"DeserializationError","httpStatus":null,"severity":"error","filePath":"python/cocoindex/_internal/serde.py","lineNumber":433,"sourceCode":"                raw = msgspec.msgpack.decode(mv[1:], ext_hook=_ext_hook)\n                if type_hint is Any:\n                    return raw\n                return pydantic_adapter.validate_python(raw)\n            except Exception as e:\n                raise DeserializationError(\n                    f\"Failed to deserialize pydantic payload ({_error_context()})\"\n                ) from e\n\n        # C: Pickle (legacy and @serialize_by_pickle)\n        if routing_byte == 0x80:\n            try:\n                return _RestrictedUnpickler(io.BytesIO(bytes(mv))).load()\n            except Exception as e:\n                raise DeserializationError(\n                    f\"Failed to deserialize pickle payload ({_error_context()})\"\n                ) from e\n\n        raise DeserializationError(\n            f\"Unknown routing byte: {routing_byte:#x} ({_error_context()})\"\n        )\n\n    return _deserialize\n\n\n# ---------------------------------------------------------------------------\n# Top-level serialize / deserialize\n# ---------------------------------------------------------------------------\n\n\ndef serialize(value: Any) -> bytes:\n    \"\"\"Serialize a value using the routing-byte protocol (C → B → A priority).\"\"\"\n    # C: Explicit pickle (user opted in — highest priority)\n    if type(value) in _SERIALIZE_BY_PICKLE_TYPES:\n        return _strict_pickle_dumps(value)\n\n    # B: Pydantic BaseModel","sourceCodeStart":415,"sourceCodeEnd":451,"githubUrl":"https://github.com/cocoindex-io/cocoindex/blob/e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b/python/cocoindex/_internal/serde.py#L415-L451","documentation":"This DeserializationError is thrown when a serialized payload's leading routing byte does not match any format the deserializer knows how to handle. The routing byte tells _deserialize which codec (e.g. pickle, native, JSON) produced the payload; an unknown value means the bytes were not produced by this library's serializer or were corrupted/truncated.","triggerScenarios":"Calling a deserialization function (the closure returned by the serializer factory) on bytes whose first byte is not one of the recognized routing-byte constants — e.g. passing raw pickle bytes that were never wrapped by the library's serializer, hand-crafted payloads, or data written by a different cocoindex version with a different byte scheme.","commonSituations":"Reading cached/indexed payloads written by an older or newer cocoindex version after upgrading; manually loading data stored in an LMDB/DB column assuming it is plain pickle; corrupted or truncated serialized blobs.","solutions":["Re-serialize the data with the same cocoindex version's serializer instead of feeding foreign bytes to _deserialize","Check for a cocoindex version mismatch between the process writing the payloads and the one reading them, and align versions","Verify the payload bytes are intact (not truncated/shifted); inspect the first byte against the codec constants in serde.py","If migrating from an old version, rebuild the stored data (re-run the pipeline) rather than decoding old payloads directly"],"exampleFix":"// before\nobj = deserialize(raw_pickle_bytes)  # unknown routing byte\n// after\nobj = deserialize(serialize(original_obj))  # round-trip through the library's serializer","handlingStrategy":"validation","validationCode":"def is_library_serialized(payload: bytes) -> bool:\n    return len(payload) > 0 and payload[0] in KNOWN_ROUTING_BYTES  # constants from serde.py","typeGuard":"def has_known_routing_byte(payload: bytes) -> bool:\n    return bool(payload) and payload[0] in {b'\\x01', b'\\x02'}  # adjust to serde constants","tryCatchPattern":"try:\n    obj = deserialize(payload)\nexcept DeserializationError as e:\n    log.error(\"unrecognized payload: %s\", e)\n    obj = recompute_and_serialize()","preventionTips":["Always serialize through the library's serializer; never feed raw pickle to _deserialize","Keep read and write sides on the same cocoindex version","Rebuild stored payloads after version upgrades"],"tags":["serialization","deserialization","data-corruption"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"e84aa99b3292c5270a4b313b2a7137ad9ce8ab3b","analyzedAt":"2026-09-08T15:59:19.997Z","contentChangedAt":"2026-09-08T15:59:19.997Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}