{"record":{"id":"47fc82c5f95d2f67","repo":"jax-ml/jax","slug":"python-int-value-too-large-to-convert-to-int32","errorCode":null,"errorMessage":"Python int {value} too large to convert to int32","messagePattern":"Python int (.+?) too large to convert to int32","errorType":"validation","errorClass":"OverflowError","httpStatus":null,"severity":"error","filePath":"jax/_src/abstract_arrays.py","lineNumber":105,"sourceCode":"# comes in a single width.\n_bool_aval = ShapedArray((), dtype=np.dtype(bool))\n_int32_aval = ShapedArray((), dtype=np.dtype(np.int32), weak_type=True)\n_int64_aval = ShapedArray((), dtype=np.dtype(np.int64), weak_type=True)\n_float32_aval = ShapedArray((), dtype=np.dtype(np.float32), weak_type=True)\n_float64_aval = ShapedArray((), dtype=np.dtype(np.float64), weak_type=True)\n_complex64_aval = ShapedArray((), dtype=np.dtype(np.complex64), weak_type=True)\n_complex128_aval = ShapedArray((), dtype=np.dtype(np.complex128), weak_type=True)\n\ncore.pytype_aval_mappings[bool] = lambda v: _bool_aval\n\ndef _int_aval(value):\n  if config.enable_x64.value:\n    if value < _int64_min or value > _int64_max:\n      raise OverflowError(f\"Python int {value} too large to convert to int64\")\n    return _int64_aval\n  else:\n    if value < _int32_min or value > _int32_max:\n      raise OverflowError(f\"Python int {value} too large to convert to int32\")\n    return _int32_aval\ncore.pytype_aval_mappings[int] = _int_aval\n\n_float_aval = lambda v: _float64_aval if config.enable_x64.value else _float32_aval\ncore.pytype_aval_mappings[float] = _float_aval\n\n_complex_aval = lambda v: _complex128_aval if config.enable_x64.value else _complex64_aval\ncore.pytype_aval_mappings[complex] = _complex_aval\n\ncore.literalable_scalar_types.update(dtypes.python_scalar_types)\ncore.literalable_types.update(dtypes.python_scalar_types)\n\n\nfor t in literals.typed_scalar_types:\n  core.pytype_aval_mappings[t] = lambda x: x.aval\ncore.literalable_scalar_types.update(literals.typed_scalar_types)\ncore.literalable_types.update(literals.typed_scalar_types)\n","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/abstract_arrays.py#L87-L123","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify with type(x)._fields and len(x) that they agree before flattening","If the class is a hand-rolled tuple subclass, stop exposing _fields or make it a correctly sized tuple","Convert the object to a real collections.namedtuple/typing.NamedTuple instance before passing to JAX","Pass is_leaf=lambda x: x is my_object to treat it as a leaf"],"exampleFix":"# before\nclass Point(tuple):\n    _fields = ('x', 'y', 'z')  # but instances may have 2 elements\n\n# after\nfrom collections import namedtuple\nPoint = namedtuple('Point', ['x', 'y'])  # arity always matches","handlingStrategy":"type-guard","validationCode":"def namedtuple_ok(x) -> bool:\n    t = type(x)\n    fields = getattr(t, '_fields', None)\n    return isinstance(fields, tuple) and len(fields) == len(x)","typeGuard":"from collections import namedtuple\n\ndef is_valid_namedtuple(x) -> bool:\n    t = type(x)\n    return (isinstance(x, tuple)\n            and isinstance(getattr(t, '_fields', None), tuple)\n            and len(t._fields) == len(x))","tryCatchPattern":null,"preventionTips":["Only use real collections.namedtuple/typing.NamedTuple for keyed flattening","Never define _fields on a plain tuple subclass","Validate deserialized namedtuple-likes before passing to JAX"],"tags":["pytree","namedtuple","jax","tree-flatten"],"backgroundTag":"pytree-structure-mismatch","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}