promtool check: Usage, Options & Common CI Errors
promtool check lints Prometheus config and alerting/recording rule files.
promtool check is the lint step that keeps a broken Prometheus rule from shipping. In CI it parses config and rule files and exits non-zero on any error, so it works as a pre-merge gate.
What it does
promtool check config validates a prometheus.yml (and referenced rule/target files); promtool check rules validates alerting and recording rule files for PromQL syntax and structure. Both exit 0 only when everything is valid.
Common usage
promtool check config prometheus.yml
promtool check rules rules/*.yml
promtool check rules --lint-fatal alerts.yml # treat lint warnings as errors
promtool check config --syntax-only prometheus.yml
promtool check metrics < metrics.txt # lint exposition formatOptions
| Subcommand / flag | What it does |
|---|---|
| check config <file> | Validate the main Prometheus config |
| check rules <files> | Validate alerting/recording rule files |
| --syntax-only | Parse config without checking referenced files |
| --lint <lint> | Lint category (e.g. all, duplicate-rules) |
| --lint-fatal | Make lint findings fail the check |
| check metrics | Lint Prometheus exposition format on stdin |
Common errors in CI
check rules reports "FAILED: <file>: N rules found ... error" with the offending PromQL, e.g. "parse error: unexpected ... " - fix the expression. check config errors like "field X not found in type config.plain" mean an unknown/misspelled config key or a version mismatch between promtool and Prometheus. A referenced rule_files glob that matches nothing passes silently - assert the files exist. By default lint warnings (e.g. duplicate rules) do not fail; add --lint-fatal to gate on them.
Using this in CI
A runner shell is not a login shell. It does not read your dotfiles, it usually has no TTY, and by default it does not stop on the first error, so a failing command in the middle of a multi-line run block can leave the job green.
# make the shell behave the way you assume it does
- name: Build
shell: bash
run: |
set -euo pipefail # exit on error, undefined vars, and pipeline failures
./do-the-thing | tee out.log