jax-ml/jax · error · ValueError

Index in subset_by_index[1] exceeds matrix size.

Error message

Index in subset_by_index[1] exceeds matrix size.

What it means

Argument validation in TPU svd: the upper bound of subset_by_index selects singular values up to the matrix rank, so subset_by_index[1] cannot exceed min(m, n). This fires when the requested upper index exceeds the matrix's rank.

Solutions

  1. Clamp end: end = min(end, min(a.shape[-2], a.shape[-1])).
  2. For full SVD, omit subset_by_index instead of passing (0, rank).
  3. Add a shape assertion in data pipelines feeding matrices of varying sizes.

Example fix

// before
svd(a, subset_by_index=(0, 64))  # fails when min(m, n) < 64
// after
rank = min(a.shape[-2], a.shape[-1])
svd(a, subset_by_index=(0, min(64, rank)))
Defensive patterns

Strategy: validation

Validate before calling

rank = min(a.shape[-2], a.shape[-1])
lo, hi = max(0, sb[0]), min(sb[1], rank)
assert lo < hi

Type guard

def fits_rank(sb, a) -> bool:
    return sb[1] <= min(a.shape[-2], a.shape[-1])

Try / catch

try:
    svd(a, subset_by_index=sb)
except ValueError as e:
    if 'exceeds matrix size' in str(e): sb = (sb[0], min(a.shape[-1], a.shape[-2]))
    else: raise

Prevention

When it happens

Trigger: svd(a, subset_by_index=(0, min(m, n) + 1)), or using the larger dimension instead of min(m, n) when computing the end bound, or running the same top-k code against smaller matrices than it was written for.

Common situations: Hard-coded k larger than the matrix's smaller dimension; batched code where some inputs have different shapes; assuming end can be max(m, n).

Related errors


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

Appendix: source

Thrown at jax/_src/tpu/linalg/svd.py:190

      'specified to use `svd` within JAX transformations.',
  )

  if subset_by_index is not None:
    if len(subset_by_index) != 2:
      raise ValueError('subset_by_index must be a tuple of size 2.')
    # Make sure subset_by_index is a concrete tuple.
    subset_by_index = (
        operator.index(subset_by_index[0]),
        operator.index(subset_by_index[1]),
    )
    if subset_by_index[0] >= subset_by_index[1]:
      raise ValueError('Got empty index range in subset_by_index.')
    if subset_by_index[0] < 0:
      raise ValueError('Indices in subset_by_index must be non-negative.')
    m, n = a.shape
    rank = n if n < m else m
    if subset_by_index[1] > rank:
      raise ValueError('Index in subset_by_index[1] exceeds matrix size.')
    if full_matrices and subset_by_index != (0, rank):
      raise ValueError(
          'full_matrices and subset_by_index cannot be both be set.'
      )
    # By convention, eigenvalues are numbered in non-decreasing order, while
    # singular values are numbered non-increasing order, so change
    # subset_by_index accordingly.
    subset_by_index = (rank - subset_by_index[1], rank - subset_by_index[0])

  m, n = a.shape
  is_flip = False
  if m < n:
    a = a.T.conj()
    m, n = a.shape
    is_flip = True

  u_out_null: Array | None
  q: Array | None

View on GitHub (pinned to 1e1c6a8fc0)