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

Check index 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 ExpressionScoreScript.setDocument(d) when values.advanceExact(d) raises IOException, wrapped in IllegalStateException with the expression source text. This is the score-script counterpart of errors 1220/1222 — the cursor cannot advance to the target document during score evaluation.

Source

Thrown at modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionScoreScript.java:90

                    return true;
                }
            });

            @Override
            public double execute(ExplanationHolder explanation) {
                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 index and shard health: GET _cluster/health?level=shards.
Inspect segment integrity: GET <index>/_segments and look for anomalies.
Refresh or restore: POST <index>/_refresh, or restore from snapshot if corruption is confirmed.
Verify no concurrent maintenance operations (force_merge, shrink, split) are running on the index.

Example fix

// No code fix — runtime I/O failure during score evaluation.
// Diagnose:
GET _cluster/health?level=shards
GET my-index/_segments
// If corrupt: restore from snapshot

Defensive patterns

Strategy: try-catch

Validate before calling

// Before running a script_score query, check shard and reader health
GET _cluster/health/<index>?level=shards

Try / catch

try {
    scoreScript.setDocument(docId);
} catch (IllegalStateException e) {
    // I/O-level failure — typically unrecoverable for this reader
    logger.error("Score expression advanceExact failed for doc [{}]: {}", docId, e.getMessage(), e);
    throw e;
}

Prevention

Keep readers fresh — avoid holding stale Searcher references across refresh cycles.
Monitor disk I/O latency on data nodes; high latency often precedes these errors.
Schedule heavy operations (force_merge, reindex) outside peak query hours.
Maintain current snapshots for fast recovery from corruption.

When it happens

Trigger: Executing a function_score or script_score query with an expression script; advanceExact fails due to an I/O error reading the segment data for document d.

Common situations: Same class of I/O issues as 1220/1222: segment corruption, closed readers, concurrent merges, disk problems on the data node.

Related errors

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