promtool "check rules" error in CI

By Daniel Zoghalchali·Latchkey

promtool check rules parses each rule group and validates every expression; when a rule has a malformed group, a bad label, or an invalid PromQL expression, it prints FAILED with the offending rule and exits 1.

What this error means

A promtool check rules rules.yml step prints "FAILED:" with a specific error (e.g. a parse error or "field ... not found") and the job fails.

Checking rules.yml
  FAILED:
  rules.yml: group "node", rule 1, "HighErrorRate": could not parse expression: parse error at char 21: unexpected character: '%'

Common causes

An invalid PromQL expression in a rule

A typo, a stray character, or an unbalanced function call makes the expr unparseable, and promtool reports the parse error with a char offset.

A malformed rule group or field

A missing record/alert key, a wrong indentation level, or an unknown field fails schema validation before PromQL is even checked.

How to fix it

Fix the rule the error points to

1. Read the group name, rule index, and char offset in the FAILED message.
2. Correct the PromQL expression or the rule fields.
3. Re-run promtool check rules until it prints SUCCESS.

promtool check rules rules.yml

Validate rules in CI before deploy

Run the check as a gate so a broken rule file never reaches a running Prometheus.

- run: promtool check rules ./prometheus/rules/*.yml

How to prevent it

• Run promtool check rules on every change to rule files.
• Use promtool test rules with unit tests for alert logic.
• Keep rule files small so parse errors are easy to locate.

Frequently asked questions

Related guides

References

• GitHub Actions documentation