promtool "could not parse expression" PromQL error in CI

By Kaveh Alemi·Latchkey

promtool reports "could not parse expression: parse error at char N" when a PromQL string in a rule or unit test is syntactically invalid: a stray operator, unbalanced parentheses, or a bad function call. The char offset points at the problem.

What this error means

promtool (check rules or test rules) fails with "could not parse expression: parse error at char N: ..." for a specific expr string.

could not parse expression: parse error at char 35: unclosed left parenthesis

Common causes

Unbalanced parentheses or brackets

A missing closing paren or bracket in a function call or aggregation leaves the parser unable to finish the expression.

An invalid operator, function, or label matcher

A misspelled function, a wrong matcher operator, or a stray character at the char offset breaks parsing.

How to fix it

Jump to the reported char offset

1. Read the "at char N" offset in the error.
2. Inspect that position for an unclosed paren, bad operator, or typo.
3. Re-run promtool to confirm the expression parses.

Sanity-check the query against the engine

Confirm the corrected expression parses by checking the rules file it lives in.

promtool check rules rules.yml

How to prevent it

• Validate PromQL with promtool in CI before merge.
• Test alert expressions with promtool test rules.
• Keep complex expressions formatted so brackets are easy to match.

Frequently asked questions

Related guides

References

• GitHub Actions documentation