elastic/elasticsearch · error · IllegalArgumentException

The difference between max_gram and min_gram in NGram Tokeni

Error message

The difference between max_gram and min_gram in NGram Tokenizer must be less than or equal to: [{}] but was [{}]. This limit can be set by changing the [{}] index level setting.

What it means

Error "The difference between max_gram and min_gram in NGram Tokenizer must be less than or equal to: [{}] but was [{}]. This limit can be set by changing the [{}] index level setting." thrown in elastic/elasticsearch.

Source

Thrown at modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/NGramTokenizerFactory.java:103

                if (customCharacters == null) {
                    throw new IllegalArgumentException("Token type: 'custom' requires setting `custom_token_chars`");
                }
                final Set<Integer> customCharSet = customCharacters.chars().boxed().collect(Collectors.toSet());
                matcher = customCharSet::contains;
            }
            builder.or(matcher);
        }
        return builder.build();
    }

    NGramTokenizerFactory(IndexSettings indexSettings, Environment environment, String name, Settings settings) {
        super(name);
        int maxAllowedNgramDiff = indexSettings.getMaxNgramDiff();
        this.minGram = settings.getAsInt("min_gram", NGramTokenizer.DEFAULT_MIN_NGRAM_SIZE);
        this.maxGram = settings.getAsInt("max_gram", NGramTokenizer.DEFAULT_MAX_NGRAM_SIZE);
        int ngramDiff = maxGram - minGram;
        if (ngramDiff > maxAllowedNgramDiff) {
            throw new IllegalArgumentException(
                "The difference between max_gram and min_gram in NGram Tokenizer must be less than or equal to: ["
                    + maxAllowedNgramDiff
                    + "] but was ["
                    + ngramDiff
                    + "]. This limit can be set by changing the ["
                    + IndexSettings.MAX_NGRAM_DIFF_SETTING.getKey()
                    + "] index level setting."
            );
        }
        this.matcher = parseTokenChars(settings);
    }

    @Override
    public Tokenizer create() {
        if (matcher == null) {
            return new NGramTokenizer(minGram, maxGram);
        } else {
            return new NGramTokenizer(minGram, maxGram) {

View on GitHub (pinned to db6a809a66)

When it happens

Trigger: Thrown at modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/NGramTokenizerFactory.java:103 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/2d341d9b45dd9f4a. Report an issue: GitHub.