jax-ml/jax · error · ValueError

sparse_format={sparse_format!r} not recognized; must be one

Error message

sparse_format={sparse_format!r} not recognized; must be one of {list(formats.keys())}

What it means

jax.experimental.sparse.empty accepts sparse_format only from a fixed set: 'bcsr','bcoo','coo','csr','csc'. Passing any other string (or wrong case, or a class) raises ValueError listing valid options.

Source

Thrown at jax/experimental/sparse/api.py:134

    _todense_impl, multiple_results=False))


def empty(shape: Sequence[int], dtype: DTypeLike | None=None, index_dtype: DTypeLike = 'int32',
          sparse_format: str = 'bcoo', **kwds) -> JAXSparse:
  """Create an empty sparse array.

  Args:
    shape: sequence of integers giving the array shape.
    dtype: (optional) dtype of the array.
    index_dtype: (optional) dtype of the index arrays.
    format: string specifying the matrix format (e.g. ['bcoo']).
    **kwds: additional keywords passed to the format-specific _empty constructor.
  Returns:
    mat: empty sparse matrix.
  """
  formats = {'bcsr': BCSR, 'bcoo': BCOO, 'coo': COO, 'csr': CSR, 'csc': CSC}
  if sparse_format not in formats:
    raise ValueError(f"sparse_format={sparse_format!r} not recognized; "
                     f"must be one of {list(formats.keys())}")
  cls = formats[sparse_format]
  return cls._empty(tuple(shape), dtype=dtype, index_dtype=index_dtype, **kwds)


def eye(N: int, M: int | None = None, k: int = 0, dtype: DTypeLike | None = None,
        index_dtype: DTypeLike = 'int32', sparse_format: str = 'bcoo', **kwds) -> JAXSparse:
  """Create 2D sparse identity matrix.

  Args:
    N: int. Number of rows in the output.
    M: int, optional. Number of columns in the output. If None, defaults to `N`.
    k: int, optional. Index of the diagonal: 0 (the default) refers to the main
       diagonal, a positive value refers to an upper diagonal, and a negative value
       to a lower diagonal.
    dtype: data-type, optional. Data-type of the returned array.
    index_dtype: (optional) dtype of the index arrays.
    format: string specifying the matrix format (e.g. ['bcoo']).

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

Use one of the exact lowercase strings: 'bcsr','bcoo','coo','csr','csc'
If you have a class, pass its name: sparse_format=BCOO.__name__.lower() or dispatch via a format map yourself

Example fix

// before
m = sparse.empty((4,4), sparse_format='lil')
// after
m = sparse.empty((4,4), sparse_format='coo')

Defensive patterns

Strategy: validation

Validate before calling

VALID = {'bcsr','bcoo','coo','csr','csc'}
assert sparse_format.lower() in VALID, f'unknown format {sparse_format}'

Type guard

def is_valid_sparse_format(fmt: str) -> bool:
    return fmt.lower() in {'bcsr','bcoo','coo','csr','csc'}

Try / catch

try:
    m = sparse.empty(shape, sparse_format=fmt)
except ValueError as e:
    fmt = 'coo'; m = sparse.empty(shape, sparse_format=fmt)

Prevention

Use lowercase format strings from the docs
Keep format names in one constant in your codebase

When it happens

Trigger: Calling jax.sparse.empty(shape, sparse_format='BCOO'), sparse_format='dia', sparse_format=BCOO (a class instead of string), or a typo like 'cos'.

Common situations: Assuming format names from scipy.sparse (e.g. 'lil','dia') exist in JAX; passing the class object; case mismatch.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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