elastic/elasticsearch · error · IllegalArgumentException

Error using {}. The variable [{}] does not exist in the exec

Error message

Error using {}. The variable [{}] does not exist in the executable expressions script.

What it means

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.

Source

Thrown at modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionScriptEngine.java:188

    public Set<ScriptContext<?>> getSupportedContexts() {
        return contexts.keySet();
    }

    private static BucketAggregationScript.Factory newBucketAggregationScriptFactory(Expression expr) {
        return parameters -> {
            ReplaceableConstDoubleValues[] functionValuesArray = new ReplaceableConstDoubleValues[expr.variables.length];
            Map<String, ReplaceableConstDoubleValues> functionValuesMap = new HashMap<>();
            for (int i = 0; i < expr.variables.length; ++i) {
                functionValuesArray[i] = new ReplaceableConstDoubleValues();
                functionValuesMap.put(expr.variables[i], functionValuesArray[i]);
            }
            return new BucketAggregationScript(parameters) {
                @Override
                public Double execute() {
                    getParams().forEach((name, value) -> {
                        ReplaceableConstDoubleValues placeholder = functionValuesMap.get(name);
                        if (placeholder == null) {
                            throw new IllegalArgumentException(
                                "Error using "
                                    + expr
                                    + ". "
                                    + "The variable ["
                                    + name
                                    + "] does not exist in the executable expressions script."
                            );
                        } else if (value instanceof Number == false) {
                            throw new IllegalArgumentException(
                                "Error using "
                                    + expr
                                    + ". "
                                    + "Executable expressions scripts can only process numbers."
                                    + "  The variable ["
                                    + name
                                    + "] is not a number."
                            );
                        } else {

View on GitHub (pinned to db6a809a66)

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.

Example fix

// before: param 'discount' is not used in the expression
GET my-index/_search
{
  "aggs": {
    "my_bucket": {
      "bucket_script": {
        "buckets_path": {"p": "price"},
        "script": {
          "lang": "expression",
          "source": "p",
          "params": {"discount": 0.1}
        }
      }
    }
  }
}
// after: remove the unused param, or add it to the expression
"source": "p * discount"
"params": {"discount": 0.1}

Defensive patterns

Strategy: validation

Validate before calling

// Before executing a bucket_script/bucket_selector, verify params match expression variables
// Extract variable names from the expression source (doc['field'] patterns and bare identifiers)
// Then ensure every key in params corresponds to a variable in the expression
// Example validation in application code:
Set<String> expressionVars = extractVariablesFromExpression(source);
for (String paramKey : params.keySet()) {
    if (!expressionVars.contains(paramKey)) {
        throw new IllegalArgumentException("Param '" + paramKey + "' is not a variable in the expression");
    }
}

Try / catch

try {
    Double result = bucketScript.execute();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("does not exist in the executable expressions script")) {
        // Remove the offending param and retry, or fix the expression
        logger.warn("Param mismatch in bucket script: {}", e.getMessage());
    }
    throw e;
}

Prevention

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.

When it happens

Trigger: 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}.

Common situations: Param name typo; leftover params from a previous version of the expression; dynamic param generation that includes keys the expression doesn't reference.

Related errors

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