keras-team/keras · error · ValueError

`sparse` may only be true if `output_mode` is `'one_hot'`…

Error message

`sparse` may only be true if `output_mode` is `'one_hot'`, `'multi_hot'`, `'count'` or `'tf_idf'`. Received: sparse={sparse} and output_mode={output_mode}

What it means

Sparse output tensors only make sense for the multi-dimensional encoded output modes ('one_hot', 'multi_hot', 'count', 'tf_idf'); with output_mode='int' the layer emits scalar indices and sparsity is meaningless. This ValueError fires at construction when sparse=True is combined with output_mode='int'.

Solutions

Drop `sparse=True` when you need integer indices.
Or switch output_mode to 'multi_hot', 'count' or 'tf_idf' to get sparse output.
For memory-efficient pipelines, keep int output and let the Embedding layer handle large vocabs.

Example fix

# before
layer = IndexLookup(sparse=True)  # output_mode defaults to 'int'

# after
layer = IndexLookup(output_mode='multi_hot', sparse=True)

Defensive patterns

Strategy: validation

Validate before calling

if sparse and output_mode == 'int':
    raise ValueError('sparse requires one_hot/multi_hot/count/tf_idf output')
layer = IndexLookup(output_mode=output_mode, sparse=sparse)

Type guard

def sparse_mode_ok(mode) -> bool:
    return mode in ('one_hot', 'multi_hot', 'count', 'tf_idf')

Prevention

Remember output_mode defaults to 'int'; setting sparse alone always conflicts.
Encode the sparse/mode compatibility rule in shared config validators.

When it happens

Trigger: `IndexLookup(sparse=True, output_mode='int')` — including the default output_mode='int' when only `sparse` is set.

Common situations: Enabling sparse output to save memory on large vocabularies while leaving output_mode at its default.

Related errors

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

Appendix: source

Thrown at keras/src/layers/preprocessing/index_lookup.py:202

            allowable_strings=(
                "int",
                "one_hot",
                "multi_hot",
                "count",
                "tf_idf",
            ),
            caller_name=self.__class__.__name__,
            arg_name="output_mode",
        )

        if invert and output_mode != "int":
            raise ValueError(
                "`output_mode` must be `'int'` when `invert` is true. "
                f"Received: output_mode={output_mode}"
            )

        if sparse and output_mode == "int":
            raise ValueError(
                "`sparse` may only be true if `output_mode` is "
                "`'one_hot'`, `'multi_hot'`, `'count'` or `'tf_idf'`. "
                f"Received: sparse={sparse} and "
                f"output_mode={output_mode}"
            )

        if idf_weights is not None and output_mode != "tf_idf":
            raise ValueError(
                "`idf_weights` should only be set if `output_mode` is "
                f"`'tf_idf'`. Received: idf_weights={idf_weights} and "
                f"output_mode={output_mode}"
            )

        super().__init__(name=name)
        self._convert_input_args = False
        self._allow_non_tensor_positional_args = True
        self.supports_jit = False

View on GitHub (pinned to 7a34a03db6)