apache/cassandra · error · IllegalArgumentException

maxTokenLength must be greater than zero

Error message

maxTokenLength must be greater than zero

What it means

StandardTokenizerOptions.OptionsBuilder.maxTokenLength requires a positive value; tokens longer than maxTokenLength are skipped during tokenization. Passing 0 or a negative number throws IllegalArgumentException.

Source

Thrown at src/java/org/apache/cassandra/index/sasi/analyzer/StandardTokenizerOptions.java:197

         * Set the min allowed token length.  Any token shorter
         * than this is skipped.
         */
        public OptionsBuilder minTokenLength(int minTokenLength)
        {
            if (minTokenLength < 1)
                throw new IllegalArgumentException("minTokenLength must be greater than zero");
            this.minTokenLength = minTokenLength;
            return this;
        }

        /**
         * Set the max allowed token length.  Any token longer
         * than this is skipped.
         */
        public OptionsBuilder maxTokenLength(int maxTokenLength)
        {
            if (maxTokenLength < 1)
                throw new IllegalArgumentException("maxTokenLength must be greater than zero");
            this.maxTokenLength = maxTokenLength;
            return this;
        }

        public StandardTokenizerOptions build()
        {
            if(allTermsToLowerCase && allTermsToUpperCase)
                throw new IllegalArgumentException("Options to normalize terms cannot be " +
                        "both uppercase and lowercase at the same time");

            StandardTokenizerOptions options = new StandardTokenizerOptions();
            options.setIgnoreStopTerms(ignoreStopTerms);
            options.setStemTerms(stemTerms);
            options.setLocale(locale);
            options.setCaseSensitive(caseSensitive);
            options.setAllTermsToLowerCase(allTermsToLowerCase);
            options.setAllTermsToUpperCase(allTermsToUpperCase);
            options.setMinTokenLength(minTokenLength);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Pass maxTokenLength >= 1
2. Omit maxTokenLength to use the default (e.g. Lucene's standard limit)
3. Ensure maxTokenLength >= minTokenLength when both are set

Example fix

// before
builder.maxTokenLength(0).build();
// after
builder.maxTokenLength(255).build();

int max = Integer.parseInt(options.getOrDefault("token_length_max", String.valueOf(DEFAULT)));
if (max < 1) throw new IllegalArgumentException("maxTokenLength must be >= 1");

try { builder.maxTokenLength(max).build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("maxTokenLength")) { builder.maxTokenLength(defaultMax).build(); } else throw e; }

When it happens

Trigger: Building StandardAnalyzer options with .maxTokenLength(0) or negative, e.g. from an option map value 'token_length_max': '0'.

Common situations: Config mistakes where users intend 'unlimited' by using 0; string-to-int conversions of malformed options.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• minTokenLength must be greater than zero
• Options to normalize terms cannot be both uppercase and lowe
• Only single character delimiters supported, was %s
• Options to normalize terms cannot be both uppercase and lowe
• REVOKE operation is not supported by AllowAllAuthorizer

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/1181b692d82a0fe3. Report an issue: GitHub.