elastic/elasticsearch · error · GeneralScriptException

Cannot use expression with text variable using {}

Error message

Cannot use expression with text variable using {}

What it means

Thrown as GeneralScriptException by ExpressionAggregationScript.setNextAggregationValue when the incoming _value for an aggregation script is not a Number. Expression scripts are strictly numeric; if a metric feeding _value is non-numeric (e.g. a string from a keyword max aggregation), binding it into the expression is impossible and the script aborts.

Source

Thrown at modules/lang-expression/src/main/java/org/elasticsearch/script/expression/ExpressionAggregationScript.java:89

            }

            @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 void setNextAggregationValue(Object value) {
                // _value isn't used in script if specialValue == null
                if (specialValue != null) {
                    if (value instanceof Number) {
                        specialValue.setValue(leaf, ((Number) value).doubleValue());
                    } else {
                        throw new GeneralScriptException("Cannot use expression with text variable using " + exprScript);
                    }
                }
            }
        };
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

1. Ensure every parent aggregation feeding _value into the expression emits numeric values.
2. Switch the upstream field to a numeric type, or use a sub-aggregation that produces numbers.
3. If you need string handling, switch the script lang from 'expression' to 'painless'.

Example fix

// before: parent 'max' agg is on a keyword field, _value is a string
{"bucket_script": {"buckets_path": {"v": "max_tag"}, "script": {"source": "_value + 1", "lang": "expression"}}}

// after: parent agg is on a numeric field
{"bucket_script": {"buckets_path": {"v": "max_price"}, "script": {"source": "_value + 1", "lang": "expression"}}}

// Ensure parent aggregations feeding _value emit numbers
// e.g. verify the buckets_path points to a numeric metric agg (avg/sum/max/min on a numeric field)
if (!isNumericAgg(parentAggType)) {
    throw new IllegalArgumentException("_value must come from a numeric aggregation for expression scripts");
}

When it happens

Trigger: Using a lang: expression script in an aggregation that receives _value (e.g. bucket_script with a parent aggregation emitting strings, or a scripted metric passing a text value). The specialValue slot is populated, but value instanceof Number is false.

Common situations: Chaining a keyword/terms aggregation's value into a numeric expression; mixing a max aggregation on a text field upstream; misconfigured bucket_script paths referencing a non-numeric bucket path.

Related errors

• Error evaluating {}
• Can't advance to doc using {}
• Member variable [{}] does not exist for date field [{}].
• Member method [{}] does not exist for date field [{}].
• Member variable [{}] does not exist for date object on field

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