quarkusio/quarkus · error · IllegalArgumentException

Cannot specify both `includes` and `excludes` terms

Error message

Cannot specify both `includes` and `excludes` terms

What it means

FT.SPELLCHECK's TERMS option accepts either INCLUDE or EXCLUDE, not both in one command. The library models includes and excludes as two separate lists on SpellCheckArgs and throws in toArgs() if both are populated, since Redis could not accept the combined command.

Source

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

     *
     * @param dialect the dialect
     * @return the current {@code SpellCheckArgs}
     */
    public SpellCheckArgs dialect(int dialect) {
        this.dialect = dialect;
        return this;
    }

    @Override
    public List<Object> toArgs() {
        List<Object> list = new ArrayList<>();
        if (distance != 0) {
            list.add("DISTANCE");
            list.add(Integer.toString(distance));
        }

        if (!includes.isEmpty() && !excludes.isEmpty()) {
            throw new IllegalArgumentException("Cannot specify both `includes` and `excludes` terms");
        }
        if (!includes.isEmpty()) {
            list.add("TERMS");
            list.add("INCLUDE");
            list.addAll(includes);
        } else if (!excludes.isEmpty()) {
            list.add("TERMS");
            list.add("EXCLUDE");
            list.addAll(excludes);
        }

        if (dialect != -1) {
            list.add("DIALECT");
            list.add(Integer.toString(dialect));
        }

        return list;
    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Populate only one of includes() or excludes() per SpellCheckArgs
2. Decide intent: to restrict suggestions use INCLUDE; to blacklist terms use EXCLUDE
3. Filter out empty list so only the non-empty one is applied

Example fix

// before
SpellCheckArgs args = new SpellCheckArgs().includes("dict1").excludes("badword");
// after
SpellCheckArgs args = new SpellCheckArgs().includes("dict1");

if (!includes.isEmpty() && !excludes.isEmpty()) throw new IllegalStateException("Use INCLUDE or EXCLUDE, not both");

try {
    redis.search().spellcheck(...).toArgs();
} catch (IllegalArgumentException e) {
    // rebuild args with only one TERMS direction
}

When it happens

Trigger: Building one SpellCheckArgs where both includes(...) and excludes(...) have been called with non-empty term collections, then serializing via toArgs().

Common situations: Collecting dictionaries/hints from configuration where both include and exclude lists are populated by default; merging two arg builders and keeping both lists.

Related errors

• `distance` must be in [1,4]
• Cannot set XX and NX together
• BYRADIUS and BYBOX cannot be used together
• Cannot use `ON HASH` and `ON JSON` at the same time
• The schema cannot be empty, you configure the indexed fields

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