{"record":{"id":"779de435f1505712","repo":"elastic/elasticsearch","slug":"can-t-advance-to-doc-using-779de4","errorCode":null,"errorMessage":"Can't advance to doc using {}","messagePattern":"Can't advance to doc using (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionFieldScript.java","lineNumber":52,"sourceCode":"\n            // Fake the scorer until setScorer is called.\n            DoubleValues values = source.getValues(leaf, null);\n\n            @Override\n            public Object execute() {\n                try {\n                    return values.doubleValue();\n                } catch (Exception exception) {\n                    throw new GeneralScriptException(\"Error evaluating \" + exprScript, exception);\n                }\n            }\n\n            @Override\n            public void setDocument(int d) {\n                try {\n                    values.advanceExact(d);\n                } catch (IOException e) {\n                    throw new IllegalStateException(\"Can't advance to doc using \" + exprScript, e);\n                }\n            }\n        };\n    }\n}\n","sourceCodeStart":34,"sourceCodeEnd":58,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionFieldScript.java#L34-L58","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Run GET <index>/_recovery and verify no ongoing or failed recovery; if segment corruption is suspected, restore the index from a snapshot.","Refresh or re-open the index reader (POST <index>/_refresh) to discard a stale reader that may have been closed.","If the error persists on specific documents, reindex the affected shard or restore from snapshot to eliminate corrupt segments."],"exampleFix":"// No code fix — this is a runtime I/O failure, not a logic error.\n// Mitigate by ensuring index health:\n// before: corrupted shard causes IllegalStateException on every search\n// after:  restore from snapshot, then re-run the same query\nPOST my-index/_refresh\nGET my-index/_recovery","handlingStrategy":"try-catch","validationCode":"// Before executing, verify the index reader is open and the shard is healthy\nGET my-index/_count  // if this fails, the reader/segment is likely in a bad state","typeGuard":null,"tryCatchPattern":"// In a plugin wrapping ExpressionFieldScript:\ntry {\n    fieldScript.setDocument(docId);\n    Object result = fieldScript.execute();\n} catch (IllegalStateException e) {\n    // advanceExact failed — log the expression source and docId, degrade gracefully\n    logger.warn(\"Failed to advance to doc [{}] for expression [{}]\", docId, e.getMessage(), e);\n    // optionally: skip this document or return a default value\n}","preventionTips":["Ensure index readers are not used after a shard refresh, relocation, or close — obtain fresh readers per search.","Monitor disk health and segment counts; schedule force_merge outside of query traffic.","Run GET <index>/_segments periodically to detect segment anomalies early.","Keep snapshots current so corrupt indices can be restored quickly."],"tags":["expression","script","runtime-field","io","lucene"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}