pypa/pip · error · ValueError

typecode should be 0-127

Error message

typecode should be 0-127

What it means

Raised by msgpack's pure-Python Packer.pack_ext_type when the integer typecode is outside the range 0–127 inclusive. The msgpack ext format uses a single unsigned byte (0–127 for user-defined types; the format reserves negative codes for system types like Timestamp). Note that pack_ext_type accepts 0–127, whereas ExtType.__new__ in ext.py:14 accepts 0–127 as well — both are consistent.

Source

Thrown at src/pip/_vendor/msgpack/fallback.py:846

        if self._autoreset:
            ret = self._buffer.getvalue()
            self._buffer = BytesIO()
            return ret

    def pack_map_header(self, n):
        if n >= 2**32:
            raise ValueError
        self._pack_map_header(n)
        if self._autoreset:
            ret = self._buffer.getvalue()
            self._buffer = BytesIO()
            return ret

    def pack_ext_type(self, typecode, data):
        if not isinstance(typecode, int):
            raise TypeError("typecode must have int type.")
        if not 0 <= typecode <= 127:
            raise ValueError("typecode should be 0-127")
        if not isinstance(data, bytes):
            raise TypeError("data must have bytes type")
        L = len(data)
        if L > 0xFFFFFFFF:
            raise ValueError("Too large data")
        if L == 1:
            self._buffer.write(b"\xd4")
        elif L == 2:
            self._buffer.write(b"\xd5")
        elif L == 4:
            self._buffer.write(b"\xd6")
        elif L == 8:
            self._buffer.write(b"\xd7")
        elif L == 16:
            self._buffer.write(b"\xd8")
        elif L <= 0xFF:
            self._buffer.write(b"\xc7" + struct.pack("B", L))
        elif L <= 0xFFFF:

View on GitHub (pinned to f399c37189)

Solutions

1. Clamp/validate the typecode to 0–127 before calling pack_ext_type.
2. Use a bounded registry/enum for extension type codes.
3. If you need more than 128 types, encode a sub-type byte inside the data payload.

Example fix

# before
packer.pack_ext_type(200, b'data')  # out of range — raises

# after
TYPE_CODE = 42  # validated to be 0-127
assert 0 <= TYPE_CODE <= 127
packer.pack_ext_type(TYPE_CODE, b'data')

def validate_ext_typecode_range(typecode: int) -> int:
    if not 0 <= typecode <= 127:
        raise ValueError(f'typecode must be 0-127, got {typecode}')
    return typecode

def is_valid_ext_typecode(typecode) -> bool:
    return isinstance(typecode, int) and 0 <= typecode <= 127

try:
    packer.pack_ext_type(code, data)
except ValueError as e:
    if '0-127' in str(e):
        code = code % 128  # wrap or choose a valid code
        packer.pack_ext_type(code, data)
    else:
        raise

When it happens

Trigger: Calling packer.pack_ext_type(typecode, data) where typecode is negative or greater than 127. Common when typecode is derived from an unvalidated user/config value or an enum with large values.

Common situations: Config-driven type codes that allow arbitrary integers; auto-incrementing counter used as typecode that exceeds 127; negative typecode intended for a system type.

Related errors

• typecode must have int type.
• data must have bytes type
• Too large data
• Got invalid value for load_only - should be one of {}
• --no-binary / --only-binary option requires 1 argument.

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/0e28adafa84be0f9. Report an issue: GitHub.