elastic/elasticsearch · critical · IllegalStateException

Can't advance to doc using {}

Error message

Can't advance to doc using {}

What it means

Thrown as IllegalStateException by ExpressionAggregationScript.setDocument when advancing the DoubleValues cursor to a document raises IOException. This indicates a low-level read failure against the index reader while positioning for per-doc evaluation in an aggregation expression script; the compiled Expression source is included for context.

Source

Thrown at modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionAggregationScript.java:78

                    return true;
                }
            });

            @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);
                }
            }

            @Override
            public void setNextAggregationValue(Object value) {
                // _value isn't used in script if specialValue == null
                if (specialValue != null) {
                    if (value instanceof Number) {
                        specialValue.setValue(leaf, ((Number) value).doubleValue());
                    } else {
                        throw new GeneralScriptException("Cannot use expression with text variable using " + exprScript);
                    }
                }
            }
        };
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

1. Check cluster/storage health and the wrapped IOException for the real cause (disk full, I/O error, closed reader).
2. Re-open or re-fetch the searcher; if a shard failed over, retry the query.
3. If a specific shard/segment is corrupted, restore from a snapshot or force a reindex.

// No client-side guard for low-level I/O; ensure cluster/storage is healthy before heavy queries
ClusterHealthResponse h = client.cluster().health(r -> r).value();
if (h != ClusterHealthStatus.GREEN && h != ClusterHealthStatus.YELLOW) {
    throw new IllegalStateException("cluster unhealthy; skip expression aggregation");
}

try {
    // aggregation with expression script
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Can't advance to doc")) {
        // inspect cause IOException; check shard/disk health
    }
    throw e;
}

When it happens

Trigger: An aggregation using a lang: expression script where values.advanceExact(doc) throws IOException during segment traversal. Usually a symptom of an I/O error reading the segment, a closed/missing reader, or corrupted fielddata column rather than a script-logic bug.

Common situations: Underlying disk/FS read errors; segments being merged or closed concurrently; corrupted index; fielddata cache eviction mid-query; hardware/NFS issues.

Related errors

• Error evaluating {}
• Cannot use expression with text variable using {}
• Error evaluating {}
• Member variable [{}] does not exist for date field [{}].
• Member method [{}] does not exist for date field [{}].

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