elastic/elasticsearch · error · IllegalArgumentException

keep requires either `keep_words` or `keep_words_path` to be

Error message

keep requires either `keep_words` or `keep_words_path` to be configured

What it means

Error "keep requires either `keep_words` or `keep_words_path` to be configured" thrown in elastic/elasticsearch.

Source

Thrown at modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/KeepWordFilterFactory.java:60

 */
public class KeepWordFilterFactory extends AbstractTokenFilterFactory {
    private final CharArraySet keepWords;
    private static final String KEEP_WORDS_KEY = "keep_words";
    private static final String KEEP_WORDS_PATH_KEY = KEEP_WORDS_KEY + "_path";
    @SuppressWarnings("unused")
    private static final String KEEP_WORDS_CASE_KEY = KEEP_WORDS_KEY + "_case"; // for javadoc

    // unsupported ancient option
    private static final String ENABLE_POS_INC_KEY = "enable_position_increments";

    KeepWordFilterFactory(IndexSettings indexSettings, Environment env, String name, Settings settings) {
        super(name);

        final List<String> arrayKeepWords = settings.getAsList(KEEP_WORDS_KEY, null);
        final String keepWordsPath = settings.get(KEEP_WORDS_PATH_KEY, null);
        if ((arrayKeepWords == null && keepWordsPath == null) || (arrayKeepWords != null && keepWordsPath != null)) {
            // we don't allow both or none
            throw new IllegalArgumentException(
                "keep requires either `" + KEEP_WORDS_KEY + "` or `" + KEEP_WORDS_PATH_KEY + "` to be configured"
            );
        }
        if (settings.get(ENABLE_POS_INC_KEY) != null) {
            throw new IllegalArgumentException(ENABLE_POS_INC_KEY + " is not supported anymore. Please fix your analysis chain");
        }
        this.keepWords = Analysis.getWordSet(env, settings, KEEP_WORDS_KEY);
    }

    @Override
    public TokenStream create(TokenStream tokenStream) {
        return new KeepWordFilter(tokenStream, keepWords);
    }
}

View on GitHub (pinned to db6a809a66)

When it happens

Trigger: Thrown at modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/KeepWordFilterFactory.java:60 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/1a3d8434048e3937. Report an issue: GitHub.