quarkusio/quarkus · error · IllegalArgumentException

Cannot set the eviction limit when using exact trimming

Error message

Cannot set the eviction limit when using exact trimming

What it means

The LIMIT option caps how many entries Redis may evict in one XTRIM call and is only valid with approximate trimming (~). When exact trimming (=, the default) is used, LIMIT has no meaning, so XTrimArgs.toArgs() throws this IllegalArgumentException when limit(long) is set but nearlyExactTrimming() was not called.

Source

Thrown at extensions/redis-client/runtime/src/main/java/io/quarkus/redis/datasource/stream/XTrimArgs.java:95

            } else {
                args.add("=");
            }
            args.add(Long.toString(maxlen));
        }

        if (minid != null) {
            args.add("MINID");
            if (approximateTrimming) {
                args.add("~");
            } else {
                args.add("=");
            }
            args.add(minid);
        }

        if (limit > 0) {
            if (!approximateTrimming) {
                throw new IllegalArgumentException("Cannot set the eviction limit when using exact trimming");
            }
            args.add("LIMIT");
            args.add(Long.toString(limit));
        }

        return args;
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Call nearlyExactTrimming() (approximate trimming) when using limit(...), e.g. new XTrimArgs().maxlen(1000).nearlyExactTrimming().limit(50)
2. Remove the limit(...) call if exact trimming is intentionally used
3. Only use limit() when slight over-retention is acceptable and trimming cost must be bounded

Example fix

// before
XTrimArgs args = new XTrimArgs().maxlen(1000).limit(50);
// after
XTrimArgs args = new XTrimArgs().maxlen(1000).nearlyExactTrimming().limit(50);

if (!approximateTrimming && limit > 0) {
    throw new IllegalArgumentException("LIMIT requires approximate trimming: call nearlyExactTrimming() when using limit()");
}

boolean supportsLimit(XTrimArgs a) {
    return a != null;
}

try {
    streamCommands.xtrim(key, args);
} catch (IllegalArgumentException e) {
    log.error("Invalid XTRIM args: " + e.getMessage());
}

When it happens

Trigger: Chaining limit(N) without nearlyExactTrimming(), e.g. new XTrimArgs().maxlen(1000).limit(50) or new XTrimArgs().minid("1234-0").limit(50), then invoking xtrim(key, args).

Common situations: Developers wanting to bound the work per trim add limit(...) but forget the default is exact trimming; copying args-building code where approximate trimming was configured elsewhere; confusion with Redis docs that show LIMIT only alongside ~.

Related errors

• Cannot use `MAXLEN` and `MINID` together
• Cannot use `MAXLEN` and `MINID` together
• Cannot set the eviction limit when using exact trimming
• Cannot combine `IDLE` and `TIME`
• `timeout` must not be `null`

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