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

Verify shard and index health: GET _cluster/health, GET /_segments — look for corrupted or unusually sized segments.

elastic/elasticsearch · error · IllegalStateException

Can't advance to doc using {}

Error message

Can't advance to doc using {}

What it means

Thrown inside ExpressionNumberSortScript.setDocument(d) when values.advanceExact(d) raises IOException, wrapped in IllegalStateException with the expression source text. This is the sort-script counterpart of error 1220 — the DoubleValues cursor cannot be positioned at the requested document in the current segment.

Source

Thrown at modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionNumberSortScript.java:81

                    return true;
                }
            });

            @Override
            public double 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 boolean needs_score() {
        return needsScores;
    }

}

View on GitHub (pinned to db6a809a66)

Solutions

Verify shard and index health: GET _cluster/health, GET <index>/_segments — look for corrupted or unusually sized segments.
Retry the query after refreshing: POST <index>/_refresh — if the reader was stale, a new reader resolves it.
If corruption is confirmed, restore the index from a snapshot or reindex into a new index.
Check for concurrent force-merge or similar operations and schedule them outside search hours.

Example fix

// No code-level fix. This is an I/O-level runtime failure.
// Diagnostic:
// before: sort by expression fails intermittently
GET my-index/_segments
// after: if corruption found, restore:
POST _snapshot/my_backup/snap_1/_restore
{ "indices": "my-index", "rename_pattern": "my-index", "rename_replacement": "my-index-restored" }

Defensive patterns

Strategy: try-catch

Validate before calling

// Before running a sort query, verify shard health
GET _cluster/health?level=shards&wait_for_status=yellow

Try / catch

try {
    sortScript.setDocument(docId);
} catch (IllegalStateException e) {
    logger.warn("Sort expression advanceExact failed for doc [{}]: {}", docId, e.getMessage(), e);
    // This is typically an I/O or reader lifecycle issue — fail the shard request
    throw e;
}

Prevention

Do not use index readers after they have been closed by a refresh or merge.
Monitor disk health on data nodes; I/O errors often surface here first.
Avoid running force_merge concurrently with heavy sort queries.
Ensure shard relocation completes before querying if the cluster is under load.

When it happens

Trigger: Executing a sort with an expression script on a shard where the underlying segment reader encounters an I/O error advancing to document d. Distinct from 1221, which fires during value retrieval; 1222 fires during cursor positioning.

Common situations: Segment reader closed mid-search (e.g., shard refresh or merge during query); corrupted doc-values structures on disk; reader lifecycle mismanagement in custom plugins that wrap expression scripts.

Related errors

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