elastic/elasticsearch · error · IllegalArgumentException

failed to build synonyms from [{rules.origin}]

Error message

failed to build synonyms from [{rules.origin}]

What it means

Any exception raised while parsing or building the Solr/Wordnet SynonymMap (parser.parse(reader) or parser.build()) is caught and rethrown as IllegalArgumentException with the offending origin label. The only lenient path is when lenient=true AND the cause is a CircuitBreakingException (heap pressure) — in that case an empty synonym map is substituted and an ERROR logged. All other parse/format errors propagate.

Source

Thrown at modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/SynonymTokenFilterFactory.java:316

    SynonymMap buildSynonyms(Analyzer analyzer, ReaderWithOrigin rules) {
        try {
            SynonymMap.Builder parser;
            if ("wordnet".equalsIgnoreCase(format)) {
                parser = new ESWordnetSynonymParser(true, expand, lenient, analyzer, circuitBreaker);
                ((ESWordnetSynonymParser) parser).parse(rules.reader);
            } else {
                parser = new ESSolrSynonymParser(true, expand, lenient, analyzer, circuitBreaker);
                ((ESSolrSynonymParser) parser).parse(rules.reader);
            }
            return parser.build();
        } catch (Exception e) {
            String message = "failed to build synonyms from [" + rules.origin + "]";
            if (lenient && e instanceof CircuitBreakingException) {
                LOGGER.error(message + ". Using an empty synonyms map in its place because lenient=true.", e);
                return EMPTY_SYNONYM_MAP;
            }

            throw new IllegalArgumentException(message, e);
        }
    }

    record ReaderWithOrigin(Reader reader, String origin, Set<String> resources) {
        ReaderWithOrigin(Reader reader, String origin) {
            this(reader, origin, Set.of());
        }
    }

    private static SynonymMap buildEmptySynonymMap() {
        try {
            return new SynonymMap.Builder().build();
        } catch (IOException e) {
            throw new UncheckedIOException(e);
        }
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

1. Inspect the origin in the message ([file:path], [inline], or [set:name]) and open that source to find the offending rule.
2. Validate each line: Solr format is comma-separated equivalents OR 'lhs => rhs'; ensure no stray punctuation.
3. If the cause is CircuitBreakingException and you can tolerate dropping synonyms, set "lenient": true on the filter to fall back to an empty map.
4. Re-save the file as UTF-8 without BOM if encoding is suspect.

Example fix

// before (malformed)
"synonyms": ["car => automobile,", "socks sock"]
// after
"synonyms": ["car,automobile", "socks,sock"]

// Validate Solr-style lines before sending
static List<String> badLines(List<String> lines) {
  List<String> bad = new ArrayList<>();
  for (String l : lines) {
    String t = l.trim();
    if (t.isEmpty()) continue;
    boolean ok = t.contains(",") || (t.contains("=>") && t.split("=>",2)[1].trim().length() > 0);
    if (!ok) bad.add(l);
  }
  return bad;
}

// Wrap index creation that includes a synonym filter
try {
  client.indices().create(c);
} catch (ResponseException e) {
  if (e.getResponse().getStatusLine().getStatusCode() == 400
      && e.getMessage().contains("failed to build synonyms")) {
    // surface the offending origin to the operator; do not retry unchanged
    reportSynonymParseFailure(e);
  } else throw e;
}

When it happens

Trigger: Loading a synonyms file or inline list whose rule syntax the chosen parser rejects: malformed Solr-style mappings ('a =>' with no RHS, stray commas), unparseable Wordnet file, duplicate or contradictory rules, or heap exhaustion during SynonymMap.build() with lenient=false.

Common situations: Editing a synonyms file by hand and breaking the 'lhs => rhs' or 'a,b,c' syntax; switching format between Solr and Wordnet without updating content; loading a multi-GB synonym set on a memory-constrained node; encoding issues (BOM, non-UTF8) in synonyms_path files.

Related errors

• synonym requires either `synonyms`, `synonyms_set` or `synon
• Token filter [{name()}] cannot be used to parse synonyms
• Token filter [{name()}] cannot be used to parse synonyms
• Invalid Mapping Rule : [{rule}]
• Extra content ${message} ('${cutOutNoNl}') matching [${patte

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/f02de1cce14a1eb6. Report an issue: GitHub.