elastic/elasticsearch · error · IllegalArgumentException

Token type: 'custom' requires setting `custom_token_chars`

Error message

Token type: 'custom' requires setting `custom_token_chars`

What it means

Error "Token type: 'custom' requires setting `custom_token_chars`" thrown in elastic/elasticsearch.

Source

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

        }
        CharMatcher.Builder builder = new CharMatcher.Builder();
        for (String characterClass : characterClasses) {
            characterClass = characterClass.toLowerCase(Locale.ROOT).trim();
            CharMatcher matcher = MATCHERS.get(characterClass);
            if (matcher == null) {
                if (characterClass.equals("custom") == false) {
                    throw new IllegalArgumentException(
                        "Unknown token type: '"
                            + characterClass
                            + "', must be one of "
                            + Stream.of(MATCHERS.keySet(), Collections.singleton("custom"))
                                .flatMap(x -> x.stream())
                                .collect(Collectors.toSet())
                    );
                }
                String customCharacters = settings.get("custom_token_chars");
                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: ["

View on GitHub (pinned to db6a809a66)

When it happens

Trigger: Thrown at modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/NGramTokenizerFactory.java:86 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/95abb5ab76ee0106. Report an issue: GitHub.