jax-ml/jax · error · ValueError

Got empty index range in subset_by_index.

Error message

Got empty index range in subset_by_index.

What it means

The subset_by_index range (start, end) must satisfy start < end; an 'empty' range like (3, 3) or (5, 2) is rejected. The SVD computation must select at least one singular value.

Source

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

  )

  max_iterations = core.concrete_or_error(
      int,
      max_iterations,
      'The `max_iterations` argument must be statically '
      '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:

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Ensure subset_by_index[0] < subset_by_index[1]; for top-k use (0, k) with k >= 1.
2. Clamp: start = max(0, start); end = max(start + 1, min(end, rank)).
3. Skip the svd call entirely when the requested count is zero instead of passing an empty range.

Example fix

// before
svd(a, subset_by_index=(k, k))
// after
if k > 0:
    svd(a, subset_by_index=(0, k))

start, end = sb
assert 0 <= start < end <= min(a.shape[-2], a.shape[-1]), f'invalid subset range {sb}'

def is_nonempty_range(sb) -> bool:
    return isinstance(sb, tuple) and len(sb) == 2 and sb[0] < sb[1]

try:
    svd(a, subset_by_index=(lo, hi))
except ValueError as e:
    if 'empty index range' in str(e): hi = lo + 1  # or skip
    else: raise

When it happens

Trigger: svd(a, subset_by_index=(k, k)) or svd(a, subset_by_index=(hi, lo)) where start >= end, e.g. computing end as start due to an off-by-one or degenerate parameter like k=0 producing (0, 0).

Common situations: Off-by-one errors when computing the range from a rank/top-k parameter; requesting zero singular values when a data-dependent count collapses to 0.

Related errors

• subset_by_index must be a tuple of size 2.
• Indices in subset_by_index must be non-negative.
• Index in subset_by_index[1] exceeds matrix size.
• full_matrices and subset_by_index cannot be both be set.
• The SVD algorithm parameter is not implemented on TPU.

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