elastic/elasticsearch · error · IllegalArgumentException

mapping requires either `mappings` or `mappings_path` to be

Error message

mapping requires either `mappings` or `mappings_path` to be configured

What it means

Error "mapping requires either `mappings` or `mappings_path` to be configured" thrown in elastic/elasticsearch.

Source

Thrown at modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/MappingCharFilterFactory.java:35

import org.elasticsearch.index.analysis.AbstractCharFilterFactory;
import org.elasticsearch.index.analysis.Analysis;
import org.elasticsearch.index.analysis.NormalizingCharFilterFactory;

import java.io.Reader;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class MappingCharFilterFactory extends AbstractCharFilterFactory implements NormalizingCharFilterFactory {

    private final NormalizeCharMap normMap;

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

        List<String> rules = Analysis.getWordList(env, settings, "mappings");
        if (rules == null) {
            throw new IllegalArgumentException("mapping requires either `mappings` or `mappings_path` to be configured");
        }

        NormalizeCharMap.Builder normMapBuilder = new NormalizeCharMap.Builder();
        parseRules(rules, normMapBuilder);
        normMap = normMapBuilder.build();
    }

    @Override
    public Reader create(Reader tokenStream) {
        return new MappingCharFilter(normMap, tokenStream);
    }

    // source => target
    private static Pattern rulePattern = Pattern.compile("(.*)\\s*=>\\s*(.*)\\s*$");

    /**
     * parses a list of MappingCharFilter style rules into a normalize char map
     */

View on GitHub (pinned to db6a809a66)

When it happens

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