{"record":{"id":"73c29d80e07d4f34","repo":"elastic/elasticsearch","slug":"can-t-advance-to-doc-using","errorCode":null,"errorMessage":"Can't advance to doc using {}","messagePattern":"Can't advance to doc using (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionAggregationScript.java","lineNumber":78,"sourceCode":"                    return true;\n                }\n            });\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            @Override\n            public void setNextAggregationValue(Object value) {\n                // _value isn't used in script if specialValue == null\n                if (specialValue != null) {\n                    if (value instanceof Number) {\n                        specialValue.setValue(leaf, ((Number) value).doubleValue());\n                    } else {\n                        throw new GeneralScriptException(\"Cannot use expression with text variable using \" + exprScript);\n                    }\n                }\n            }\n        };\n    }\n}\n","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionAggregationScript.java#L60-L96","documentation":"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.","triggerScenarios":"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.","commonSituations":"Underlying disk/FS read errors; segments being merged or closed concurrently; corrupted index; fielddata cache eviction mid-query; hardware/NFS issues.","solutions":["Check cluster/storage health and the wrapped IOException for the real cause (disk full, I/O error, closed reader).","Re-open or re-fetch the searcher; if a shard failed over, retry the query.","If a specific shard/segment is corrupted, restore from a snapshot or force a reindex."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// No client-side guard for low-level I/O; ensure cluster/storage is healthy before heavy queries\nClusterHealthResponse h = client.cluster().health(r -> r).value();\nif (h != ClusterHealthStatus.GREEN && h != ClusterHealthStatus.YELLOW) {\n    throw new IllegalStateException(\"cluster unhealthy; skip expression aggregation\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    // aggregation with expression script\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Can't advance to doc\")) {\n        // inspect cause IOException; check shard/disk health\n    }\n    throw e;\n}","preventionTips":["Monitor disk and shard health; I/O faults underlie most advanceExact failures.","Avoid querying shards that are being recovered/merged when possible.","Keep fielddata cache sized to avoid eviction mid-query."],"tags":["elasticsearch","lang-expression","expression-script","aggregation","io","runtime"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:31:55.035Z"}