elastic/elasticsearch · error · IllegalStateException

Can't advance to doc using {}

Error message

Can't advance to doc using {}

What it means

Thrown inside ExpressionFieldScript.setDocument(d) when values.advanceExact(d) raises an IOException. The expression engine wraps the I/O failure in an IllegalStateException, appending the compiled expression source text so you can identify which script was running. advanceExact positions the Lucene DoubleValues cursor at a specific document; an IOException there means the segment reader could not satisfy the read.

Source

Thrown at modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionFieldScript.java:52

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

            @Override
            public Object 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

  1. Check cluster health and shard recovery status via GET _cluster/health and GET _cat/recovery — if a shard is being relocated, retry after it completes.
  2. Run GET <index>/_recovery and verify no ongoing or failed recovery; if segment corruption is suspected, restore the index from a snapshot.
  3. Refresh or re-open the index reader (POST <index>/_refresh) to discard a stale reader that may have been closed.
  4. If the error persists on specific documents, reindex the affected shard or restore from snapshot to eliminate corrupt segments.

Example fix

// No code fix — this is a runtime I/O failure, not a logic error.
// Mitigate by ensuring index health:
// before: corrupted shard causes IllegalStateException on every search
// after:  restore from snapshot, then re-run the same query
POST my-index/_refresh
GET my-index/_recovery
Defensive patterns

Strategy: try-catch

Validate before calling

// Before executing, verify the index reader is open and the shard is healthy
GET my-index/_count  // if this fails, the reader/segment is likely in a bad state

Try / catch

// In a plugin wrapping ExpressionFieldScript:
try {
    fieldScript.setDocument(docId);
    Object result = fieldScript.execute();
} catch (IllegalStateException e) {
    // advanceExact failed — log the expression source and docId, degrade gracefully
    logger.warn("Failed to advance to doc [{}] for expression [{}]", docId, e.getMessage(), e);
    // optionally: skip this document or return a default value
}

Prevention

When it happens

Trigger: A runtime_fields or field script using "lang":"expression" is evaluated per-document. The underlying LeafReader.getNumericDocValues (or similar) throws IOException while advancing to doc ID d — e.g., the segment was closed, merged away, or the disk returned a read error.

Common situations: Index segment corruption after a hard crash; using a script on a searcher that was already closed (e.g., after a shard relocation); transient disk I/O errors on heavily loaded nodes; force-merge concurrently with a long-running search.

Related errors

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