{"record":{"id":"794f619c3f660f01","repo":"elastic/elasticsearch","slug":"token-filter-name-cannot-be-used-to-parse-sy","errorCode":null,"errorMessage":"Token filter [{name()}] cannot be used to parse synonyms","messagePattern":"Token filter \\[(.+?)\\] cannot be used to parse synonyms","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/WordDelimiterGraphTokenFilterFactory.java","lineNumber":96,"sourceCode":"        // If set, causes trailing \"'s\" to be removed for each subword: \"O'Neil's\" => \"O\", \"Neil\"\n        flags |= getFlag(STEM_ENGLISH_POSSESSIVE, settings, \"stem_english_possessive\", true);\n        // If not null is the set of tokens to protect from being delimited\n        flags |= getFlag(IGNORE_KEYWORDS, settings, \"ignore_keywords\", false);\n        // If set, suppresses processing terms with KeywordAttribute#isKeyword()=true.\n        Set<?> protectedWords = Analysis.getWordSet(env, settings, \"protected_words\");\n        this.protoWords = protectedWords == null ? null : CharArraySet.copy(protectedWords);\n        this.flags = flags;\n        this.adjustOffsets = settings.getAsBoolean(\"adjust_offsets\", true);\n    }\n\n    @Override\n    public TokenStream create(TokenStream tokenStream) {\n        return new WordDelimiterGraphFilter(tokenStream, adjustOffsets, charTypeTable, flags, protoWords);\n    }\n\n    @Override\n    public TokenFilterFactory getSynonymFilter() {\n        throw new IllegalArgumentException(\"Token filter [\" + name() + \"] cannot be used to parse synonyms\");\n    }\n\n    private static int getFlag(int flag, Settings settings, String key, boolean defaultValue) {\n        if (settings.getAsBoolean(key, defaultValue)) {\n            return flag;\n        }\n        return 0;\n    }\n}\n","sourceCodeStart":78,"sourceCodeEnd":106,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/WordDelimiterGraphTokenFilterFactory.java#L78-L106","documentation":"WordDelimiterGraphTokenFilterFactory.getSynonymFilter() is hard-coded to throw IllegalArgumentException. Elasticsearch asks each token filter for a 'synonym filter' (the analyzer used to parse synonym rule text) via TokenFilterFactory.getSynonymFilter(); the word-delimiter-graph filter refuses because its multi-token splitting corrupts the parsing of synonym entries. There is no configuration that enables it.","triggerScenarios":"A synonym/synonym_graph filter that uses an analyzer whose chain resolves to a word_delimiter_graph filter when building the synonym map — either by naming that analyzer explicitly via the 'analyzer' field, or because the index default analyzer contains word_delimiter_graph and no explicit synonym analyzer is set.","commonSituations":"Building a search analyzer that splits on case/number boundaries and then using the same analyzer (or a parent) to parse synonyms; reusing a custom analyzer for both indexing and synonym parsing.","solutions":["On the synonym/synonym_graph filter, set \"analyzer\" explicitly to a lightweight analyzer that does NOT contain word_delimiter_graph (e.g. \"standard\", \"whitespace\", or a custom chain ending before the delimiter).","Keep the word-delimiter filter only in the search/index analyzers, never in the analyzer used to read synonym rules.","Re-test with _analyze to confirm the synonym-parsing analyzer produces single tokens per rule entry."],"exampleFix":"// before\n\"my_syn\": { \"type\": \"synonym\", \"synonyms\": [\"foo,bar\"], \"analyzer\": \"my_wdf_analyzer\" }\n// after\n\"my_syn\": { \"type\": \"synonym\", \"synonyms\": [\"foo,bar\"], \"analyzer\": \"standard\" }","handlingStrategy":"validation","validationCode":"// Reject synonym filters that resolve to a word_delimiter_graph analyzer\nstatic String checkSynonymAnalyzer(Map<String,Object> filter, Set<String> wdAnalyzers) {\n  if (\"synonym\".equals(filter.get(\"type\")) || \"synonym_graph\".equals(filter.get(\"type\"))) {\n    Object a = filter.getOrDefault(\"analyzer\", \"<default>\");\n    if (wdAnalyzers.contains(a)) return \"analyzer \" + a + \" contains word_delimiter_graph\";\n  }\n  return null;\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set an explicit lightweight 'analyzer' on synonym/synonym_graph filters.","Never reuse the search analyzer (which may include word_delimiter_graph) for synonym parsing.","Validate with _analyze that the chosen analyzer emits a single token per synonym term."],"tags":["analysis","synonyms","word-delimiter","configuration"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:31:55.035Z"}