jax-ml/jax · error · OverflowError

Python int {value} too large to convert to int64

Error message

Python int {value} too large to convert to int64

What it means

When flattening a custom PyTree node with keys, jaxlib iterates the returned key_leaf_pairs and requires each entry to be a 2-element tuple (key, leaf). This error is raised when an element of that iterable is not a tuple of size 2 (e.g. a bare leaf, a 3-tuple, a list, or a string).

Source

Thrown at jax/_src/abstract_arrays.py:101

_int64_min = np.iinfo(np.int64).min
_int64_max = np.iinfo(np.int64).max

# Note: all python scalar types are weak except bool, because bool only
# 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:

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Ensure each element of key_leaf_pairs is exactly a 2-tuple whose first item is a key entry (often jax.tree_util.SequenceKey(i), GetAttrKey(name), or a string)
2. If keys are not meaningful, still return 2-tuples, e.g. [(None, child), ...] per your registration convention
3. Add tree_flatten_with_path smoke test for each registered type

Example fix

# before
def _iter_keys(obj):
    return ([c for c in obj.children], None)  # entries are not (key, leaf) tuples

# after
from jax.tree_util import SequenceKey
def _iter_keys(obj):
    return ([(SequenceKey(i), c) for i, c in enumerate(obj.children)], None)

def valid_pairs(pairs) -> bool:
    return all(isinstance(p, tuple) and len(p) == 2 for p in pairs)

def has_valid_flatten_hook(obj) -> bool:
    try:
        jtu.tree_flatten_with_path(obj)
        return True
    except (ValueError, TypeError):
        return False

When it happens

Trigger: A custom node's to_iterable_with_keys returns [(child1, child2), ...] (pairs of children) or [child, ...] (bare leaves) instead of [(key, child), ...]; triggered by tree_flatten_with_path, tree_map_with_path, or any API that needs keypaths.

Common situations: Converting a to_iterable hook to the keyed variant and forgetting to prepend keys; using namedtuples/lists instead of tuples for the pairs; returning dictionary items() when the protocol expects explicit key objects (SequenceKey/GetAttrKey/FlattenedIndexKey).

Related errors

• numpy masked arrays are not supported as direct inputs to JA
• The names should be exclusive and should not intersect in `n
• Python int {value} too large to convert to int32
• The return value of the policies should be a boolean. Got: {
• prevent_cse must be a bool or tuple of bools, got {type(prev

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