elastic/elasticsearch · error · IllegalArgumentException

synonym requires either `synonyms`, `synonyms_set` or `synon

Error message

synonym requires either `synonyms`, `synonyms_set` or `synonyms_path` to be configured

What it means

The synonym / synonym_graph token filter needs exactly one source of synonym rules. SynonymTokenFilterFactory.SynonymsSource.fromSettings walks three mutually-exclusive keys in priority order — INLINE ('synonyms'), INDEX ('synonyms_set'), LOCAL_FILE ('synonyms_path') — and throws when none of the three is present in the filter's Settings. The check is a simple hasValue() probe per key, so an empty value still counts as 'present' and will fail later at parse time rather than here.

Source

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

            this.settingName = settingName;
        }

        public abstract ReaderWithOrigin getRulesReader(SynonymTokenFilterFactory factory, IndexCreationContext context);

        public String getSettingName() {
            return settingName;
        }

        public static SynonymsSource fromSettings(Settings settings) {
            SynonymsSource synonymsSource;
            if (settings.hasValue(SynonymsSource.INLINE.getSettingName())) {
                synonymsSource = SynonymsSource.INLINE;
            } else if (settings.hasValue(SynonymsSource.INDEX.getSettingName())) {
                synonymsSource = SynonymsSource.INDEX;
            } else if (settings.hasValue(SynonymsSource.LOCAL_FILE.getSettingName())) {
                synonymsSource = SynonymsSource.LOCAL_FILE;
            } else {
                throw new IllegalArgumentException(
                    "synonym requires either `"
                        + SynonymsSource.INLINE.getSettingName()
                        + "`, `"
                        + SynonymsSource.INDEX.getSettingName()
                        + "` or `"
                        + SynonymsSource.LOCAL_FILE.getSettingName()
                        + "` to be configured"
                );
            }

            return synonymsSource;
        }
    }

    private final String format;
    private final boolean expand;
    private final boolean lenient;
    protected final Settings settings;

View on GitHub (pinned to db6a809a66)

Solutions

1. Add exactly one of: "synonyms": ["a,b"], "synonyms_set": "my-set", or "synonyms_path": "analysis/synonyms.txt" to the filter's settings.
2. Verify the key spelling matches one of the three exact names (synonyms / synonyms_set / synonyms_path).
3. Confirm the key lives inside the filter object, not at analyzer or index-settings level.
4. For synonyms_set, ensure the synonyms set was previously created via PUT _synonyms and is referenced by its name.

Example fix

// before
{
  "settings": {
    "analysis": {
      "filter": { "my_syn": { "type": "synonym" } }
    }
  }
}
// after
{
  "settings": {
    "analysis": {
      "filter": {
        "my_syn": {
          "type": "synonym",
          "synonyms": ["car,automobile", "socks,sock"]
        }
      }
    }
  }
}

// Pre-flight before creating an index with a synonym filter
Function<Map<String,Object>, String> checkSynSource = filter -> {
  boolean hasInline  = filter.containsKey("synonyms");
  boolean hasIndex   = filter.containsKey("synonyms_set");
  boolean hasPath    = filter.containsKey("synonyms_path");
  int n = (hasInline?1:0) + (hasIndex?1:0) + (hasPath?1:0);
  if (n == 0) return "missing: add one of synonyms | synonyms_set | synonyms_path";
  if (n > 1) return "ambiguous: pick exactly one source";
  return null; // ok
};

When it happens

Trigger: Creating or updating an index whose analyzer defines a filter of type 'synonym' or 'synonym_graph' without any of: 'synonyms', 'synonyms_set', 'synonyms_path'. Also triggered via the _analyze API with such a filter, or via an index template whose settings omit all three keys.

Common situations: Migrating an older analyzer config and dropping the source key; typo'ing the key (e.g. 'synonym' singular, 'synonym_path'); placing the key at the wrong nesting level (under the analyzer instead of under the filter); copying a synonym_set definition but forgetting to also reference it by name.

Related errors

• Token filter [{name()}] cannot be used to parse synonyms
• Token filter [{name()}] cannot be used to parse synonyms
• Cannot merge SEARCH_TIME and INDEX_TIME analysis mode.
• failed to build synonyms from [{rules.origin}]
• update_offsets is not supported anymore. Please fix your ana

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