What causes "Can't advance to doc using {}" in elastic/elasticsearch?

Check cluster and shard health: GET _cluster/health?level=shards.

elastic/elasticsearch · error · IllegalStateException

Can't advance to doc using {}

Error message

Can't advance to doc using {}

What it means

Thrown inside ExpressionTermSetQueryScript.setDocument(d) when values.advanceExact(d) raises IOException, wrapped in IllegalStateException with the expression source text. This is the terms-set-query counterpart of errors 1220/1222/1224 — the Lucene DoubleValues cursor cannot be positioned at the target document.

Source

Thrown at modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionTermSetQueryScript.java:59

        return new TermsSetQueryScript() {
            // Fake the scorer until setScorer is called.
            DoubleValues values = source.getValues(leaf, null);

            @Override
            public Number execute() {
                try {
                    return values.doubleValue();
                } catch (Exception exception) {
                    throw new GeneralScriptException("Error evaluating " + exprScript, exception);
                }
            }

            @Override
            public void setDocument(int d) {
                try {
                    values.advanceExact(d);
                } catch (IOException e) {
                    throw new IllegalStateException("Can't advance to doc using " + exprScript, e);
                }
            }
        };
    }

}

View on GitHub (pinned to db6a809a66)

Solutions

Check cluster and shard health: GET _cluster/health?level=shards.
Inspect segments for corruption: GET <index>/_segments.
Refresh the index to get a fresh reader: POST <index>/_refresh.
Restore from snapshot if segment corruption is confirmed.

Example fix

// No code fix — runtime I/O failure during terms_set query evaluation.
// Diagnose shard/segment health:
GET _cluster/health?level=shards
GET my-index/_segments
// Restore if corrupt:
POST _snapshot/my_backup/snap_1/_restore
{"indices": "my-index"}

Defensive patterns

Strategy: try-catch

Validate before calling

// Before running a terms_set query, verify shard health
GET _cluster/health/<index>?level=shards

Try / catch

try {
    termsSetScript.setDocument(docId);
} catch (IllegalStateException e) {
    logger.error("Terms set expression advanceExact failed for doc [{}]: {}", docId, e.getMessage(), e);
    // I/O-level failure — typically fail the shard request
    throw e;
}

Prevention

Monitor disk I/O and segment health on data nodes.
Avoid running force_merge or shard relocation concurrently with terms_set queries.
Keep snapshots current for fast recovery from segment corruption.
Run GET <index>/_segments to detect anomalies before they cause query failures.

When it happens

Trigger: Executing a terms_set query with an expression script; advanceExact fails due to an I/O error reading segment data for document d. Distinct from 1238 which fires during value retrieval.

Common situations: Segment corruption; reader closed mid-query (refresh or merge during search); disk I/O errors; concurrent shard relocation causing reader invalidation.

Related errors

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