jax-ml/jax · error · OverflowError

Python int {value} too large to convert to int32

Error message

Python int {value} too large to convert to int32

What it means

When flattening a namedtuple one level with keys, jaxlib reads the class's _fields attribute and requires it to be a tuple of the same length as the tuple instance. If _fields is not a tuple, or its length differs from the instance's length, this error is thrown.

Source

Thrown at jax/_src/abstract_arrays.py:105

# comes in a single width.
_bool_aval = ShapedArray((), dtype=np.dtype(bool))
_int32_aval = ShapedArray((), dtype=np.dtype(np.int32), weak_type=True)
_int64_aval = ShapedArray((), dtype=np.dtype(np.int64), weak_type=True)
_float32_aval = ShapedArray((), dtype=np.dtype(np.float32), weak_type=True)
_float64_aval = ShapedArray((), dtype=np.dtype(np.float64), weak_type=True)
_complex64_aval = ShapedArray((), dtype=np.dtype(np.complex64), weak_type=True)
_complex128_aval = ShapedArray((), dtype=np.dtype(np.complex128), weak_type=True)

core.pytype_aval_mappings[bool] = lambda v: _bool_aval

def _int_aval(value):
  if config.enable_x64.value:
    if value < _int64_min or value > _int64_max:
      raise OverflowError(f"Python int {value} too large to convert to int64")
    return _int64_aval
  else:
    if value < _int32_min or value > _int32_max:
      raise OverflowError(f"Python int {value} too large to convert to int32")
    return _int32_aval
core.pytype_aval_mappings[int] = _int_aval

_float_aval = lambda v: _float64_aval if config.enable_x64.value else _float32_aval
core.pytype_aval_mappings[float] = _float_aval

_complex_aval = lambda v: _complex128_aval if config.enable_x64.value else _complex64_aval
core.pytype_aval_mappings[complex] = _complex_aval

core.literalable_scalar_types.update(dtypes.python_scalar_types)
core.literalable_types.update(dtypes.python_scalar_types)


for t in literals.typed_scalar_types:
  core.pytype_aval_mappings[t] = lambda x: x.aval
core.literalable_scalar_types.update(literals.typed_scalar_types)
core.literalable_types.update(literals.typed_scalar_types)

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Verify with type(x)._fields and len(x) that they agree before flattening
2. If the class is a hand-rolled tuple subclass, stop exposing _fields or make it a correctly sized tuple
3. Convert the object to a real collections.namedtuple/typing.NamedTuple instance before passing to JAX
4. Pass is_leaf=lambda x: x is my_object to treat it as a leaf

Example fix

# before
class Point(tuple):
    _fields = ('x', 'y', 'z')  # but instances may have 2 elements

# after
from collections import namedtuple
Point = namedtuple('Point', ['x', 'y'])  # arity always matches

def namedtuple_ok(x) -> bool:
    t = type(x)
    fields = getattr(t, '_fields', None)
    return isinstance(fields, tuple) and len(fields) == len(x)

from collections import namedtuple

def is_valid_namedtuple(x) -> bool:
    t = type(x)
    return (isinstance(x, tuple)
            and isinstance(getattr(t, '_fields', None), tuple)
            and len(t._fields) == len(x))

When it happens

Trigger: Calling jax.tree_util.flatten_one_level(instance, with_keys=True) (or tree_flatten_with_path) on an object whose type has a _fields attribute but is not a well-formed namedtuple — e.g. a plain tuple subclass with a custom _fields, a namedtuple instance tampered with via __new__ bypass, or a namedtuple-like class where _fields is a list or has wrong arity.

Common situations: Libraries that mimic namedtuple (collections.namedtuple alternatives, dataclasses exposing _fields, typing.NamedTuple re-implementations) that are isinstance-compatible with tuple; patching or monkey-typing _fields at runtime; stale cached classes after hot-reload.

Related errors

• numpy masked arrays are not supported as direct inputs to JA
• The names should be exclusive and should not intersect in `n
• Expected named tuple, got %s.
• Python int {value} too large to convert to int64
• The return value of the policies should be a boolean. Got: {

AI-assisted analysis of jax-ml/jax@1e1c6a8fc0 (2026-08-27). Data as JSON: /api/errors/47fc82c5f95d2f67. Report an issue: GitHub.