apache/cassandra · error · IllegalArgumentException

minTokenLength must be greater than zero

Error message

minTokenLength must be greater than zero

What it means

StandardTokenizerOptions.OptionsBuilder.minTokenLength validates that the minimum token length is at least 1; a token shorter than minTokenLength is skipped by the tokenizer. Passing 0 or a negative value throws IllegalArgumentException since it would be meaningless.

Source

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

        {
            this.allTermsToUpperCase = allTermsToUpperCase;
            return this;
        }

        public OptionsBuilder alwaysLowerCaseTerms(boolean allTermsToLowerCase)
        {
            this.allTermsToLowerCase = allTermsToLowerCase;
            return this;
        }

        /**
         * 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()
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Pass minTokenLength >= 1 (1 disables length filtering effectively)
2. Omit minTokenLength to use the default
3. Clamp parsed option values: Math.max(1, value)

Example fix

// before
new StandardTokenizerOptions.Builder().minTokenLength(0).build();
// after
new StandardTokenizerOptions.Builder().minTokenLength(1).build();

int min = Integer.parseInt(options.getOrDefault("token_length_min", "1"));
if (min < 1) throw new IllegalArgumentException("minTokenLength must be >= 1");

try { builder.minTokenLength(min).build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("minTokenLength")) { builder.minTokenLength(1).build(); } else throw e; }

When it happens

Trigger: Building StandardAnalyzer options with .minTokenLength(0) or a negative int, e.g. from a parsed 'token_length_min' option value of '0'.

Common situations: Users specifying min token length 0 in index options expecting 'no limit'; parsing config values without lower-bound checks.

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

• maxTokenLength 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/168ffc2af9093fed. Report an issue: GitHub.