{"record":{"id":"99153e765d15c5a7","repo":"elastic/elasticsearch","slug":"error-using-the-variable-does-not-exist-i","errorCode":null,"errorMessage":"Error using {}. The variable [{}] does not exist in the executable expressions script.","messagePattern":"Error using (.+?)\\. The variable \\[(.+?)\\] does not exist in the executable expressions script\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionScriptEngine.java","lineNumber":188,"sourceCode":"    public Set<ScriptContext<?>> getSupportedContexts() {\n        return contexts.keySet();\n    }\n\n    private static BucketAggregationScript.Factory newBucketAggregationScriptFactory(Expression expr) {\n        return parameters -> {\n            ReplaceableConstDoubleValues[] functionValuesArray = new ReplaceableConstDoubleValues[expr.variables.length];\n            Map<String, ReplaceableConstDoubleValues> functionValuesMap = new HashMap<>();\n            for (int i = 0; i < expr.variables.length; ++i) {\n                functionValuesArray[i] = new ReplaceableConstDoubleValues();\n                functionValuesMap.put(expr.variables[i], functionValuesArray[i]);\n            }\n            return new BucketAggregationScript(parameters) {\n                @Override\n                public Double execute() {\n                    getParams().forEach((name, value) -> {\n                        ReplaceableConstDoubleValues placeholder = functionValuesMap.get(name);\n                        if (placeholder == null) {\n                            throw new IllegalArgumentException(\n                                \"Error using \"\n                                    + expr\n                                    + \". \"\n                                    + \"The variable [\"\n                                    + name\n                                    + \"] does not exist in the executable expressions script.\"\n                            );\n                        } else if (value instanceof Number == false) {\n                            throw new IllegalArgumentException(\n                                \"Error using \"\n                                    + expr\n                                    + \". \"\n                                    + \"Executable expressions scripts can only process numbers.\"\n                                    + \"  The variable [\"\n                                    + name\n                                    + \"] is not a number.\"\n                            );\n                        } else {","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionScriptEngine.java#L170-L206","documentation":"Thrown inside BucketAggregationScript.execute() when a parameter name passed to the script does not match any variable declared in the compiled expression. The expression engine builds a map of variables from expr.variables at factory creation time; if a param key has no corresponding variable, the placeholder lookup returns null and this error is thrown.","triggerScenarios":"Using a bucket selector or bucket script aggregation with \"lang\":\"expression\" and passing params that include a key not used in the expression source. For example, expression source is \"doc['price'].value\" but params include {\"discount\": 0.1}.","commonSituations":"Param name typo; leftover params from a previous version of the expression; dynamic param generation that includes keys the expression doesn't reference.","solutions":["Match param names exactly to variables in the expression source — check spelling and case.","Remove unused params from the params map before passing them to the script.","Review the expression source and list every variable; ensure each param key corresponds to one of those variables.","If params are generated dynamically, filter them against the expression's variable list before execution."],"exampleFix":"// before: param 'discount' is not used in the expression\nGET my-index/_search\n{\n  \"aggs\": {\n    \"my_bucket\": {\n      \"bucket_script\": {\n        \"buckets_path\": {\"p\": \"price\"},\n        \"script\": {\n          \"lang\": \"expression\",\n          \"source\": \"p\",\n          \"params\": {\"discount\": 0.1}\n        }\n      }\n    }\n  }\n}\n// after: remove the unused param, or add it to the expression\n\"source\": \"p * discount\"\n\"params\": {\"discount\": 0.1}","handlingStrategy":"validation","validationCode":"// Before executing a bucket_script/bucket_selector, verify params match expression variables\n// Extract variable names from the expression source (doc['field'] patterns and bare identifiers)\n// Then ensure every key in params corresponds to a variable in the expression\n// Example validation in application code:\nSet<String> expressionVars = extractVariablesFromExpression(source);\nfor (String paramKey : params.keySet()) {\n    if (!expressionVars.contains(paramKey)) {\n        throw new IllegalArgumentException(\"Param '\" + paramKey + \"' is not a variable in the expression\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    Double result = bucketScript.execute();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"does not exist in the executable expressions script\")) {\n        // Remove the offending param and retry, or fix the expression\n        logger.warn(\"Param mismatch in bucket script: {}\", e.getMessage());\n    }\n    throw e;\n}","preventionTips":["Maintain a single source of truth for expression variables and param keys — generate params from the expression's variable list.","When updating an expression, audit all callers that pass params and remove stale keys.","Document the expected param names alongside the expression source in your configuration.","Use integration tests that exercise the expression with its full param set."],"tags":["expression","script","aggregation","params","bucket-script"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}