apache/cassandra · error · IllegalArgumentException

Options to normalize terms cannot be both uppercase and lowe

Error message

Options to normalize terms cannot be both uppercase and lowercase at the same time

What it means

StandardTokenizerOptions.build() rejects a configuration where allTermsToLowerCase and allTermsToUpperCase are both true, since terms cannot be normalized to both lower and upper case simultaneously. Throws IllegalArgumentException before constructing the options.

Source

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

            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);
            options.setMaxTokenLength(maxTokenLength);
            return options;
        }
    }

    public static StandardTokenizerOptions buildFromMap(Map<String, String> optionsMap)
    {
        OptionsBuilder optionsBuilder = new OptionsBuilder();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set only one of lower/upper case normalization to true
Leave both false to preserve original token casing
Add pre-build validation of the flags

Example fix

// before
builder.setAllTermsToLowerCase(true).setAllTermsToUpperCase(true).build();
// after
builder.setAllTermsToLowerCase(true).setAllTermsToUpperCase(false).build();

Defensive patterns

Strategy: validation

Validate before calling

if (allTermsToLowerCase && allTermsToUpperCase) throw new IllegalArgumentException("Only one of lowercase/uppercase term normalization may be enabled");

Try / catch

try { StandardTokenizerOptions opts = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("both uppercase and lowercase")) { builder.setAllTermsToUpperCase(false); StandardTokenizerOptions opts = builder.build(); } }

Prevention

Model normalization as a single enum in config, not two booleans
Validate merged option maps before building tokenizer options

When it happens

Trigger: new StandardTokenizerOptions.Builder().setAllTermsToLowerCase(true).setAllTermsToUpperCase(true).build(), or building from option maps with both 'normalize_lowercase' and 'normalize_uppercase' set.

Common situations: Merged/overlapping option maps from tooling; users treating the two flags as independent toggles.

Related errors

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