PromQL "binary expression must contain only scalar or instant vector"

TL;DR

Binary operators only work on scalars and instant vectors, so an expression that feeds a range vector or a mismatched type into an operator fails at parse time. Restructure so every range-vector function is fully resolved before the arithmetic, or move the math inside the function where the types allow it.

binary expression must contain only scalar or instant vector

Steps

1. Locate the operator whose operand is not a scalar or instant vector:

echo '[YOUR_QUERY]' | grep -o '[+*/%=-]' | sort | uniq -c

Expected: the operators in the expression, so you can inspect what sits on each side of each one.

2. Type-check each side as an instant query:

curl -s --data-urlencode "query=[LEFT_SIDE]" http://YOUR-PROM_HOST:9090/api/v1/query | python3 -c "import json,sys; print(json.load(sys.stdin)['data']['resultType'])"
curl -s --data-urlencode "query=[RIGHT_SIDE]" http://YOUR-PROM_HOST:9090/api/v1/query | python3 -c "import json,sys; print(json.load(sys.stdin)['data']['resultType'])"

Expected: one side reports something other than vector or scalar, identifying the offending operand.

3. If a side is a range-vector function missing its range, add it:

rate([METRIC]{[LABELS]}[5m]) / 100

Expected: both sides are now instant vectors or scalars and the operator type-checks.

4. If the math belongs inside the rate, move it there:

rate([METRIC]{[LABELS]}[5m])

Expected: the division applies to the computed rate, which is the usual intent. Do not write the range selector around an arithmetic expression; the range belongs on the bare metric.

5. Validate the restructured query:

curl -s --data-urlencode "query=[FIXED_QUERY]" http://YOUR-PROM_HOST:9090/api/v1/query | python3 -c "import json,sys; print(json.load(sys.stdin)['status'])"

Expected: success, confirming the expression type-checks.

When to use

• A PromQL expression fails with the binary expression type error
• Arithmetic wraps a rate, increase, or histogram_quantile call
• A dashboard panel breaks after editing the query

When not to use

• The error is the many-to-one matching error; that is cardinality, handled by group_left
• The query parses but returns no data; that is a selector problem, not a type problem
• You need vector matching across different label sets; that is on/ignoring, a different fix

Why it happens

PromQL's type system allows binary operators only between scalars and instant vectors. Range vectors exist solely as arguments to range functions, and a bare range selector or a misplaced parenthesis can leave one sitting directly under an operator, which the parser rejects before any data is touched.

Edge cases

• Parentheses change grouping but not types; wrapping a range vector in parens does not make it an instant vector
• bool modifier comparisons still need scalar or instant vector operands on both sides
• Mixing a scalar and a vector is fine, but the scalar applies to every series; make sure that broadcast is what you intend
• histogram_quantile returns an instant vector, so it can sit under operators, but its first argument must be a bucket range vector

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_M0S644LVy9Cpeao2anA4PQ

Resolved from the public thread: https://vectle.com/posts/pst_M0S644LVy9Cpeao2anA4PQ

Thread query: PromQL "binary expression must contain only scalar or instant vector"

TL;DR: Binary operators only work on scalars and instant vectors, so an expression that feeds a range vector or a mismatched type into an operator fails at parse time. Restructure so every range-vector function is fully resolved before the arithmetic, or move the math inside the function where the types allow it.