jax-ml/jax · error · ValueError

The input `a` must be at least a 2-D array.

Error message

The input `a` must be at least a 2-D array.

What it means

jax.scipy.linalg.polar computes the polar decomposition of matrices and requires input with at least 2 dimensions. Scalars, 1-D vectors, or 0/1-d arrays fail the ndim check and raise ValueError. The function applies a vectorized 2-D kernel with signature '(m,n)->...', so a matrix (possibly batched) is mandatory.

Source

Thrown at jax/_src/scipy/linalg.py:2132

    P is positive-semidefinite Matrix:

    >>> with jnp.printoptions(precision=2, suppress=True):
    ...     print(P)
    [[4.79 3.25 1.23]
     [3.25 3.06 2.01]
     [1.23 2.01 2.91]]

    The original matrix can be reconstructed by multiplying the U and P:

    >>> a_reconstructed = U @ P
    >>> jnp.allclose(a, a_reconstructed)
    Array(True, dtype=bool)

  .. _QDWH: https://epubs.siam.org/doi/abs/10.1137/090774999
  """
  arr = jnp.asarray(a)
  if arr.ndim < 2:
    raise ValueError("The input `a` must be at least a 2-D array.")

  if side not in ["right", "left"]:
    raise ValueError("The argument `side` must be either 'right' or 'left'.")

  sig = "(m,n)->(m,n),(n,n)" if side == "right" else "(m,n)->(m,n),(m,m)"
  return jnp_vectorize.vectorize(
      partial(_polar_2d, side=side, method=method, eps=eps,
              max_iterations=max_iterations),
      signature=sig)(arr)


@jit
def _sqrtm_triu(T: Array) -> Array:
  """
  Implements Björck, Å., & Hammarling, S. (1983).
      "A Schur method for the square root of a matrix". Linear algebra and
      its applications", 52, 127-140.
  """

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

  1. Reshape to 2-D: a.reshape(-1, 1) or a[:, None] for column vectors
  2. Check arr.ndim >= 2 before calling polar
  3. Ensure upstream slicing keeps the matrix rank (avoid np.squeeze on all axes)

Example fix

# before
U, H = polar(v)  # v shape (3,)
# after
U, H = polar(v.reshape(-1, 1))  # shape (3, 1)
Defensive patterns

Strategy: validation

Validate before calling

a = jnp.asarray(a)
if a.ndim < 2:
    a = a.reshape(1, -1) if a.ndim == 1 else a.reshape(1, 1)
U, H = jax.scipy.linalg.polar(a)

Type guard

def is_matrix_like(a) -> bool:
    import jax.numpy as jnp
    return jnp.asarray(a).ndim >= 2

Try / catch

try:
    polar(a)
except ValueError as e:
    if 'must be at least a 2-D' in str(e):
        a = jnp.asarray(a).reshape(-1, 1); polar(a)
    else: raise

Prevention

When it happens

Trigger: Passing a Python number, a 0-d jnp array, or a 1-D array (e.g. a vector of shape (n,)) to polar().

Common situations: Feeding a flattened vector or an unwrapped scalar from an upstream pipeline; batched code where a leading axis was accidentally squeezed.

Related errors

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