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
- Clamp end: end = min(end, min(a.shape[-2], a.shape[-1])).
- For full SVD, omit subset_by_index instead of passing (0, rank).
- 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
- Derive end from the input's shape every call, never hard-code k.
- In batched pipelines with varying shapes, clamp per-sample or pad inputs.
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
- full_matrices and subset_by_index cannot be both be set.
- Got empty index range in subset_by_index.
- Indices in subset_by_index must be non-negative.
- subset_by_index must be a tuple of size 2.
- Only the POLAR (which is also DEFAULT on TPU) SVD algorithm…
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 | NoneView on GitHub (pinned to 1e1c6a8fc0)