elastic/elasticsearch · error · IllegalArgumentException

update_offsets is not supported anymore. Please fix your ana

Error message

update_offsets is not supported anymore. Please fix your analysis chain

What it means

The trim token filter no longer supports the update_offsets option — Lucene's TrimFilter always shifts offsets, and the legacy flag was removed. The constructor performs an explicit settings.get("update_offsets") presence check and rejects any value (true or false) with IllegalArgumentException. There is no migration path: the option must be removed.

Source

Thrown at modules/analysis-common/src/main/java/org/elasticsearch/analysis/common/TrimTokenFilterFactory.java:27

package org.elasticsearch.analysis.common;

import org.apache.lucene.analysis.TokenStream;
import org.apache.lucene.analysis.miscellaneous.TrimFilter;
import org.elasticsearch.common.settings.Settings;
import org.elasticsearch.env.Environment;
import org.elasticsearch.index.IndexSettings;
import org.elasticsearch.index.analysis.AbstractTokenFilterFactory;
import org.elasticsearch.index.analysis.NormalizingTokenFilterFactory;

public class TrimTokenFilterFactory extends AbstractTokenFilterFactory implements NormalizingTokenFilterFactory {

    private static final String UPDATE_OFFSETS_KEY = "update_offsets";

    TrimTokenFilterFactory(IndexSettings indexSettings, Environment env, String name, Settings settings) {
        super(name);
        if (settings.get(UPDATE_OFFSETS_KEY) != null) {
            throw new IllegalArgumentException(UPDATE_OFFSETS_KEY + " is not supported anymore. Please fix your analysis chain");
        }
    }

    @Override
    public TokenStream create(TokenStream tokenStream) {
        return new TrimFilter(tokenStream);
    }

}

View on GitHub (pinned to db6a809a66)

Solutions

1. Delete the "update_offsets" key from the trim filter definition.
2. If offset preservation is genuinely required, redesign the analysis chain (e.g. use a char filter or a different token filter) rather than trying to restore the flag.
3. Re-run the index/template create after the edit.

Example fix

// before
"filter": { "my_trim": { "type": "trim", "update_offsets": "true" } }
// after
"filter": { "my_trim": { "type": "trim" } }

// Strip the removed flag from any trim filter before sending
static void sanitize(Map<String,Object> filter) {
  if ("trim".equals(filter.get("type"))) {
    filter.remove("update_offsets");
  }
}

When it happens

Trigger: Defining an analyzer with a filter of type 'trim' whose settings include the key 'update_offsets' with any value. Reproduced on index create, index settings update, template apply, or _analyze.

Common situations: Carrying forward an analyzer definition from a pre-7.x or Lucene-5.x cluster; copy-pasting a tutorial that still mentions update_offsets; CI failing after a cluster upgrade because the option was removed in a recent version.

Related errors

• Cannot merge SEARCH_TIME and INDEX_TIME analysis mode.
• synonym requires either `synonyms`, `synonyms_set` or `synon
• length parameter must be provided
• Token filter [{name()}] cannot be used to parse synonyms
• Token filter [{name()}] cannot be used to parse synonyms

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