elastic/elasticsearch · error · IllegalArgumentException

Token filter [{name}] cannot be used to parse synonyms

Error message

Token filter [{name}] cannot be used to parse synonyms

What it means

Error "Token filter [{name}] cannot be used to parse synonyms" thrown in elastic/elasticsearch.

Source

Thrown at modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/CommonGramsTokenFilterFactory.java:56

            throw new IllegalArgumentException(
                "missing or empty [common_words] or [common_words_path] configuration for common_grams token filter"
            );
        }
    }

    @Override
    public TokenStream create(TokenStream tokenStream) {
        CommonGramsFilter filter = new CommonGramsFilter(tokenStream, words);
        if (queryMode) {
            return new CommonGramsQueryFilter(filter);
        } else {
            return filter;
        }
    }

    @Override
    public TokenFilterFactory getSynonymFilter() {
        throw new IllegalArgumentException("Token filter [" + name() + "] cannot be used to parse synonyms");
    }
}

View on GitHub (pinned to db6a809a66)

When it happens

Trigger: Thrown at modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/CommonGramsTokenFilterFactory.java:56 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/9d0a93be7433a92c. Report an issue: GitHub.