quarkusio/quarkus · error · IllegalArgumentException

`distance` must be in [1,4]

Error message

`distance` must be in [1,4]

What it means

SpellCheckArgs.distance(int) validates that the FT.SPELLCHECK DISTANCE parameter is between 1 and 4, matching RediSearch's allowed range. The library throws IllegalArgumentException eagerly at argument-construction time rather than sending an invalid value to Redis. Values outside [1,4] have no meaning in RediSearch's Levenshtein distance model.

Source

Thrown at extensions/redis-client/runtime/src/main/java/io/quarkus/redis/datasource/search/SpellCheckArgs.java:28

import io.smallrye.mutiny.helpers.ParameterValidation;

public class SpellCheckArgs implements RedisCommandExtraArguments {

    private int distance;

    private final List<String> includes = new ArrayList<>();
    private final List<String> excludes = new ArrayList<>();
    private int dialect = -1;

    /**
     * Sets the maximum Levenshtein distance for spelling suggestions (default: 1, max: 4).
     *
     * @param distance the distance
     * @return the current {@code SpellCheckArgs}
     */
    public SpellCheckArgs distance(int distance) {
        if (distance < 1 || distance > 4) {
            throw new IllegalArgumentException("`distance` must be in [1,4]");
        }
        this.distance = distance;
        return this;
    }

    /**
     * Specifies an inclusion of a custom dictionary named {@code dict}
     *
     * @param dict the dictionaries
     * @return the current {@code SpellCheckArgs}
     */
    public SpellCheckArgs includes(String... dict) {
        ParameterValidation.doesNotContainNull(notNullOrEmpty(dict, "dict"), "dict");
        Collections.addAll(includes, dict);
        return this;
    }

    /**

View on GitHub (pinned to e1c734241f)

Solutions

1. Pass a distance value between 1 and 4 inclusive, e.g. args.distance(2)
2. If 'no fuzzy matching' is desired, do not call distance() at all or skip spellcheck for that term
3. Clamp the user-supplied value: Math.max(1, Math.min(4, userDistance))

Example fix

// before
SpellCheckArgs args = new SpellCheckArgs().distance(0);
// after
SpellCheckArgs args = new SpellCheckArgs().distance(1);

if (distance < 1 || distance > 4) throw new IllegalArgumentException("distance must be in [1,4]");
args.distance(distance);

boolean isValidDistance(int d) { return d >= 1 && d <= 4; }

When it happens

Trigger: Calling new SpellCheckArgs().distance(0) or .distance(5) or any negative value before executing a spellcheck query.

Common situations: Developers guess that distance 0 means 'exact match only' or copy a Levenshtein threshold from another library; assuming the range is inclusive of 0 or unbounded above.

Related errors

• Cannot specify both `includes` and `excludes` terms
• `pattern` must not be `null`
• Invalid integer encoding for a bit field type: " + bit + ".
• `bits` must be strictly positive
• Signed integers support only up to 64 bits

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/0d5db4be985ca34a. Report an issue: GitHub.