{"record":{"id":"cfb4018c6e13d0dd","repo":"jax-ml/jax","slug":"python-int-value-too-large-to-convert-to-int64","errorCode":null,"errorMessage":"Python int {value} too large to convert to int64","messagePattern":"Python int (.+?) too large to convert to int64","errorType":"validation","errorClass":"OverflowError","httpStatus":null,"severity":"error","filePath":"jax/_src/abstract_arrays.py","lineNumber":101,"sourceCode":"_int64_min = np.iinfo(np.int64).min\n_int64_max = np.iinfo(np.int64).max\n\n# Note: all python scalar types are weak except bool, because bool only\n# 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:","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/abstract_arrays.py#L83-L119","documentation":"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).","triggerScenarios":"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.","commonSituations":"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).","solutions":["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)","If keys are not meaningful, still return 2-tuples, e.g. [(None, child), ...] per your registration convention","Add tree_flatten_with_path smoke test for each registered type"],"exampleFix":"# before\ndef _iter_keys(obj):\n    return ([c for c in obj.children], None)  # entries are not (key, leaf) tuples\n\n# after\nfrom jax.tree_util import SequenceKey\ndef _iter_keys(obj):\n    return ([(SequenceKey(i), c) for i, c in enumerate(obj.children)], None)","handlingStrategy":"validation","validationCode":"def valid_pairs(pairs) -> bool:\n    return all(isinstance(p, tuple) and len(p) == 2 for p in pairs)","typeGuard":"def has_valid_flatten_hook(obj) -> bool:\n    try:\n        jtu.tree_flatten_with_path(obj)\n        return True\n    except (ValueError, TypeError):\n        return False","tryCatchPattern":null,"preventionTips":["Always build key_leaf_pairs as [(key, child), ...] with explicit key objects","Use SequenceKey/GetAttrKey/FlattenedIndexKey from jax.tree_util rather than ad-hoc keys","Test tree_map_with_path on each registered type"],"tags":["pytree","custom-node","jax","tree-flatten-with-path"],"backgroundTag":"pytree-custom-node-protocol-violation","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}