elastic/elasticsearch · error · IllegalArgumentException

The [nGram] token filter name was deprecated in 6.4 and cann

Error message

The [nGram] token filter name was deprecated in 6.4 and cannot be used in new indices. Please change the filter name to [ngram] instead.

What it means

Error "The [nGram] token filter name was deprecated in 6.4 and cannot be used in new indices. Please change the filter name to [ngram] instead." thrown in elastic/elasticsearch.

Source

Thrown at modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/CommonAnalysisPlugin.java:286

        filters.put("hindi_normalization", HindiNormalizationFilterFactory::new);
        filters.put("hyphenation_decompounder", requiresAnalysisSettings(HyphenationCompoundWordTokenFilterFactory::new));
        filters.put("indic_normalization", IndicNormalizationFilterFactory::new);
        filters.put("keep", requiresAnalysisSettings(KeepWordFilterFactory::new));
        filters.put("keep_types", requiresAnalysisSettings(KeepTypesFilterFactory::new));
        filters.put("keyword_marker", requiresAnalysisSettings(KeywordMarkerTokenFilterFactory::new));
        filters.put("kstem", KStemTokenFilterFactory::new);
        filters.put("length", LengthTokenFilterFactory::new);
        filters.put("limit", LimitTokenCountFilterFactory::new);
        filters.put("lowercase", LowerCaseTokenFilterFactory::new);
        filters.put("min_hash", MinHashTokenFilterFactory::new);
        filters.put("multiplexer", MultiplexerTokenFilterFactory::new);
        filters.put("ngram", NGramTokenFilterFactory::new);
        filters.put("nGram", (IndexSettings indexSettings, Environment environment, String name, Settings settings) -> {
            return new NGramTokenFilterFactory(indexSettings, environment, name, settings) {
                @Override
                public TokenStream create(TokenStream tokenStream) {
                    if (indexSettings.getIndexVersionCreated().onOrAfter(IndexVersions.V_8_0_0)) {
                        throw new IllegalArgumentException(
                            "The [nGram] token filter name was deprecated in 6.4 and cannot be used in new indices. "
                                + "Please change the filter name to [ngram] instead."
                        );
                    } else {
                        deprecationLogger.warn(
                            DeprecationCategory.ANALYSIS,
                            "nGram_deprecation",
                            "The [nGram] token filter name is deprecated and will be removed in a future version. "
                                + "Please change the filter name to [ngram] instead."
                        );
                    }
                    return super.create(tokenStream);
                }

            };
        });
        filters.put("pattern_capture", requiresAnalysisSettings(PatternCaptureGroupTokenFilterFactory::new));
        filters.put("pattern_replace", requiresAnalysisSettings(PatternReplaceTokenFilterFactory::new));

View on GitHub (pinned to db6a809a66)

When it happens

Trigger: Thrown at modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/CommonAnalysisPlugin.java:286 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/ce8d9bbf19a64f0d. Report an issue: GitHub.