keras-team/keras · error · ValueError

If `max_tokens` is set for `IntegerLookup`, it must be great

Error message

If `max_tokens` is set for `IntegerLookup`, it must be greater than 1. Received: max_tokens={max_tokens}

What it means

IntegerLookup requires max_tokens > 1 because at least one OOV slot plus one real token must fit; a value of 1 or less makes the lookup meaningless. The check runs in __init__ before any other setup.

Source

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

        vocabulary=None,
        vocabulary_dtype="int64",
        idf_weights=None,
        invert=False,
        output_mode="int",
        sparse=False,
        pad_to_max_tokens=False,
        oov_method="floormod",
        salt=None,
        name=None,
        **kwargs,
    ):
        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}"

View on GitHub (pinned to 7a34a03db6)

Solutions

Set max_tokens to at least 2 (num_oov_indices + at least one vocabulary slot)
Leave max_tokens=None to let the layer size itself from adapt()
Validate computed caps: max_tokens = max(2, num_unique + num_oov_indices)

Example fix

// before
layer = IntegerLookup(max_tokens=1)
// after
layer = IntegerLookup(max_tokens=None)  # or >= 2

Defensive patterns

Strategy: validation

Validate before calling

if max_tokens is not None:
    assert max_tokens > 1, 'max_tokens must be > 1'

Prevention

Clamp computed caps: max(2, n)
Omit max_tokens to let adapt size the layer

When it happens

Trigger: Passing max_tokens=1, 0, or a negative number to keras.layers.IntegerLookup(); computing max_tokens from data (e.g. number of unique values) that turns out to be <=1.

Common situations: Config files with placeholder max_tokens=1; dynamically sized layers over very low-cardinality integer features.

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 keras-team/keras@7a34a03db6 (2026-08-25). Data as JSON: /api/errors/27a257133a492b6e. Report an issue: GitHub.