jax-ml/jax · error · TypeError

JAX encountered invalid PRNG key data: expected key_data.ndi

Error message

JAX encountered invalid PRNG key data: expected key_data.ndim >= 1; got ndim={key_data.ndim}

What it means

JAX requires PRNG key_data to be at least 1-dimensional because the trailing dimensions encode the key shape for the RNG implementation. This TypeError fires when a 0-d (scalar) array is passed as key_data, which cannot hold the two uint32 words a threefry key needs. It is raised by _check_prng_key_data during PRNGKeyArray construction or jax.random.random_wrap.

Source

Thrown at jax/_src/random/prng.py:132

prngs: dict[str, PRNGImpl] = {}

def register_prng(impl: PRNGImpl):
  if impl.name in prngs:
    raise ValueError(f'PRNG with name {impl.name} already registered: {impl}')
  prngs[impl.name] = impl


# -- PRNG key arrays

def _check_prng_key_data(impl, key_data: typing.Array):
  ndim = len(impl.key_shape)
  if not all(hasattr(key_data, attr) for attr in ['ndim', 'shape', 'dtype']):
    raise TypeError("JAX encountered invalid PRNG key data: expected key_data "
                    f"to have ndim, shape, and dtype attributes. Got {key_data}")
  if key_data.ndim < 1:
    raise TypeError("JAX encountered invalid PRNG key data: expected "
                    f"key_data.ndim >= 1; got ndim={key_data.ndim}")
  if key_data.shape[-ndim:] != impl.key_shape:
    raise TypeError("JAX encountered invalid PRNG key data: expected key_data.shape to "
                    f"end with {impl.key_shape}; got shape={key_data.shape} for {impl=}")
  if key_data.dtype not in [np.uint32, float0]:
    raise TypeError("JAX encountered invalid PRNG key data: expected key_data.dtype = uint32; "
                    f"got dtype={key_data.dtype}")


class PRNGKeyArray(Array):
  """An array of PRNG keys backed by an RNG implementation.

  This class lifts the definition of a PRNG, provided in the form of a
  ``PRNGImpl``, into an array-like pytree class. Instances of this
  class behave like an array whose base elements are keys, hiding the
  fact that keys are typically arrays (of ``uint32`` dtype) themselves.

  PRNGKeyArrays are also restricted relative to JAX arrays in that

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Pass at least a 1-d array whose trailing dims match the impl key_shape: jax.random.random_wrap(jnp.uint32([lo, hi]), impl=...)
2. If the scalar is a seed, use jax.random.key(seed) instead of wrapping
3. Check intermediate reshape/squeeze calls that may have collapsed key data to 0-d

Example fix

// before
key = jax.random.random_wrap(jnp.uint32(42), impl='threefry2x32')

// after
key = jax.random.key(42)

assert jnp.asarray(data).ndim >= 1, 'key_data must be at least 1-d'

import jax.numpy as jnp
def has_key_ndim(x) -> bool:
    return hasattr(x, 'ndim') and x.ndim >= 1

When it happens

Trigger: Passing a scalar jnp.uint32 value to jax.random.random_wrap; squeezing/broadcasting key data down to 0-d before wrapping; reshaping key arrays with reshape(()) accidentally.

Common situations: Data-processing pipelines that flatten or squeeze arrays generically before passing them on; refactoring code where a key was previously a length-2 vector but became a scalar after indexing.

Related errors

• JAX encountered invalid PRNG key data: expected key_data to
• JAX encountered invalid PRNG key data: expected key_data.sha
• iteration over a 0-d array
• Formatting arguments to checkify.check need to be PyTrees of
• check_error takes an Error as argument, got type {type(error

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