jax-ml/jax · error · ValueError

full_matrices and subset_by_index cannot be both be set.

Error message

full_matrices and subset_by_index cannot be both be set.

What it means

full_matrices=True is incompatible with any subset_by_index other than the trivial full range (0, rank). A partial SVD cannot also request full-dimension U and Vt matrices.

Source

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

  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

  if full_matrices and m > n:

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Set full_matrices=False when using a partial subset_by_index.
2. Or pass subset_by_index=(0, rank) (equivalent to full range) if full_matrices=True is required.
3. Adjust downstream code that assumed U/Vt had full dims; with full_matrices=False shapes are (m, k) and (k, n).

Example fix

// before
u, s, vt = svd(a, full_matrices=True, subset_by_index=(0, k))
// after
u, s, vt = svd(a, full_matrices=False, subset_by_index=(0, k))

rank = min(a.shape[-2], a.shape[-1])
full = full_matrices and sb in (None, (0, rank))
u, s, vt = svd(a, full_matrices=full, subset_by_index=sb)

try:
    svd(a, full_matrices=True, subset_by_index=sb)
except ValueError as e:
    if 'cannot be both be set' in str(e):
        u, s, vt = svd(a, full_matrices=False, subset_by_index=sb)
    else: raise

When it happens

Trigger: svd(a, full_matrices=True, subset_by_index=(0, k)) with k < min(m, n); note that subset_by_index=(0, rank) is explicitly allowed.

Common situations: Copy-pasting existing svd(..., full_matrices=True) code and adding subset_by_index for a top-k speedup; forgetting full_matrices defaults or was set for shape-compatibility downstream.

Related errors

• subset_by_index must be a tuple of size 2.
• Got empty index range in subset_by_index.
• Indices in subset_by_index must be non-negative.
• Index in subset_by_index[1] exceeds matrix size.
• cannot specify both devices and num_cores

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