keras-team/keras · error · ValueError

`sparse=True` can only be used with the TensorFlow backend.

Error message

`sparse=True` can only be used with the TensorFlow backend.

What it means

IntegerLookup can emit sparse tensors only through TensorFlow's SparseTensor machinery. __init__ rejects sparse=True when keras.backend is not tensorflow, regardless of whether TF is installed.

Source

Thrown at keras/src/layers/preprocessing/integer_lookup.py:370

    ):
        if not tf.available:
            raise ImportError(
                "Layer IntegerLookup requires TensorFlow. "
                "Install it via `pip install tensorflow`."
            )
        if max_tokens is not None and max_tokens <= 1:
            raise ValueError(
                "If `max_tokens` is set for `IntegerLookup`, it must be "
                f"greater than 1. Received: max_tokens={max_tokens}"
            )
        if num_oov_indices < 0:
            raise ValueError(
                "The value of `num_oov_indices` argument for `IntegerLookup` "
                "must >= 0. Received: num_oov_indices="
                f"{num_oov_indices}"
            )
        if sparse and backend.backend() != "tensorflow":
            raise ValueError(
                "`sparse=True` can only be used with the TensorFlow backend."
            )
        if vocabulary_dtype != "int64":
            raise ValueError(
                "Only `vocabulary_dtype='int64'` is supported "
                "at this time. Received: "
                f"vocabulary_dtype={vocabulary_dtype}"
            )
        super().__init__(
            max_tokens=max_tokens,
            num_oov_indices=num_oov_indices,
            mask_token=mask_token,
            oov_token=oov_token,
            vocabulary=vocabulary,
            vocabulary_dtype=vocabulary_dtype,
            idf_weights=idf_weights,
            invert=invert,
            output_mode=output_mode,

View on GitHub (pinned to 7a34a03db6)

Solutions

1. Switch backend before building the model: keras.config.set_backend('tensorflow') (or KERAS_BACKEND=tensorflow)
2. Drop sparse=True and consume dense output
3. Move the lookup to a separate TF-only preprocessing stage

Example fix

// before (KERAS_BACKEND=jax)
layer = IntegerLookup(sparse=True)
// after
import os; os.environ['KERAS_BACKEND']='tensorflow'
import keras
layer = keras.layers.IntegerLookup(sparse=True)

import keras
if sparse and keras.backend.backend() != 'tensorflow':
    sparse = False  # or fail loudly at config time

When it happens

Trigger: keras.layers.IntegerLookup(sparse=True) while keras.backend is 'jax', 'torch' or 'numpy'; default environment KERAS_BACKEND=jax in a multi-backend install.

Common situations: Porting a TF2 preprocessing pipeline to JAX/PyTorch with Keras 3; setting the backend via env var but keeping sparse output for memory efficiency.

Related errors

• `sparse` may only be true if `output_mode` is `"one_hot"`, `
• `sparse` may only be true if `output_mode` is `'one_hot'`, `
• `adapt()` can only be called on a tf.data.Dataset or a dict
• `sparse=True` can only be used with the TensorFlow backend.
• Invalid value for argument `output_mode`. Expected one of {a

AI-assisted analysis of keras-team/keras@7a34a03db6 (2026-08-25). Data as JSON: /api/errors/9eb2c6cd691a2354. Report an issue: GitHub.