promtool check rules: Validate Alerting Rules
promtool check rules <file...> parses Prometheus rule files and exits non-zero if any rule is malformed, catching broken alerts in CI.
A typo in an alerting rule silently disables an alert until production needs it. promtool check rules validates the syntax in the pipeline so a bad rule fails the PR instead.
What it does
promtool check rules reads one or more rule files, validates the YAML structure and each PromQL expression, and reports how many rules were found. It exits 0 on success and non-zero on any parse or expression error.
Common usage
promtool check rules rules/*.yml
# validate a single file
promtool check rules alerts.yml
# combine with unit tests
promtool test rules tests/*.ymlOptions
| Command / flag | What it does |
|---|---|
| check rules <file...> | Validate one or more rule files |
| --lint=duplicates | Lint mode (e.g. duplicate rule detection) |
| --lint-fatal | Treat lint warnings as failures |
| test rules <file...> | Run rule unit tests (separate command) |
In CI
Run promtool check rules on every change to the rules directory; its non-zero exit fails the job with no extra scripting. Add --lint-fatal so lint warnings (like duplicate rule names) also block the merge rather than being ignored.
Common errors in CI
"FAILED: <file>: yaml: line N: ..." means the YAML itself is malformed (indentation, tabs). "FAILED: ... could not parse expression: parse error" means the PromQL is invalid, for example an unclosed brace in a selector. "FAILED: ... unrecognized character" usually means a smart quote pasted into the expr. Each FAILED line drives a non-zero exit.