{"record":{"id":"6b2957dc55cc5a53","repo":"jax-ml/jax","slug":"python-int-value-too-large-to-convert-to-dtype","errorCode":null,"errorMessage":"Python int {value} too large to convert to {dtype}","messagePattern":"Python int (.+?) too large to convert to (.+?)","errorType":"validation","errorClass":"OverflowError","httpStatus":null,"severity":"error","filePath":"jax/_src/dtypes.py","lineNumber":466,"sourceCode":"  >>> scalar_type_to_dtype(int)\n  dtype('int32')\n  >>> scalar_type_to_dtype(float)\n  dtype('float32')\n  >>> scalar_type_to_dtype(complex)\n  dtype('complex64')\n  >>> scalar_type_to_dtype(int)\n  dtype('int32')\n  >>> scalar_type_to_dtype(int, 0)\n  dtype('int32')\n  >>> scalar_type_to_dtype(int, 1 << 63)  # doctest: +IGNORE_EXCEPTION_DETAIL\n  Traceback (most recent call last):\n  OverflowError: Python int 9223372036854775808 too large to convert to int32\n  \"\"\"\n  dtype = canonicalize_dtype(python_scalar_types_to_dtypes[typ])\n  if typ is int and value is not None:\n    iinfo = np.iinfo(dtype)\n    if value < iinfo.min or value > iinfo.max:\n      raise OverflowError(f\"Python int {value} too large to convert to {dtype}\")\n  return dtype\n\n\ndef coerce_to_array(x: Any, dtype: DTypeLike | None = None) -> np.ndarray:\n  \"\"\"Coerces a scalar or NumPy array to an np.array.\n\n  Handles Python scalar type promotion according to JAX's rules, not NumPy's\n  rules.\n  \"\"\"\n  if dtype is None and type(x) in python_scalar_types:\n    dtype = scalar_type_to_dtype(type(x), x)\n  return np.asarray(x, dtype)\n\niinfo = ml_dtypes.iinfo\nfinfo = ml_dtypes.finfo\n\ndef _issubclass(a: Any, b: Any) -> bool:\n  \"\"\"Determines if ``a`` is a subclass of ``b``.","sourceCodeStart":448,"sourceCodeEnd":484,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/dtypes.py#L448-L484","documentation":"scalar_type_to_dtype validates that a Python int fits the (canonicalized) target dtype — under 32-bit mode int becomes int32, so ints outside [-2^31, 2^31) raise OverflowError before silent wraparound.","triggerScenarios":"Calling coerce_to_array / scalar_type_to_dtype with a large Python int (e.g. 2**40, hashing offsets, dataset ids) while x64 is disabled (default), so int32 is the target.","commonSituations":"Large IDs/indices from datasets; hashes or timestamps as ints; code written assuming 64-bit ints without jax_enable_x64.","solutions":["Enable 64-bit mode at process start: `import jax; jax.config.update('jax_enable_x64', True)` (must be set before arrays are created)","Cast explicitly: jnp.array(value, dtype=jnp.int64) after enabling x64, or use jnp.int64-aware code","Keep values within int32 range or store as float64/uint32 as appropriate"],"exampleFix":"# before\njnp.array(2**40)  # OverflowError\n\n# after\nimport jax\njax.config.update('jax_enable_x64', True)\njnp.array(2**40)","handlingStrategy":"validation","validationCode":"import numpy as np, jax\ninfo = np.iinfo(jnp.int32 if not jax.config.x64_enabled else jnp.int64)\nassert info.min <= value <= info.max, f'{value} out of range'","typeGuard":null,"tryCatchPattern":"try:\n    coerce_to_array(value)\nexcept OverflowError:\n    jax.config.update('jax_enable_x64', True)  # only if before array creation\n    coerce_to_array(value)","preventionTips":["Enable jax_enable_x64 at startup if ints exceed int32","Validate large IDs/indices against the active int width"],"tags":["jax","overflow","int64","x64"],"backgroundTag":"integer-overflow","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}