promtool check config: Validate prometheus.yml

promtool check config prometheus.yml parses the main config and every rule file it points to, exiting non-zero on any error.

A bad prometheus.yml means Prometheus refuses to start or reload. Validating it in CI catches scrape-config and relabeling mistakes before they reach the server.

What it does

promtool check config reads prometheus.yml, validates its structure (scrape configs, relabel rules, alerting, remote write) and then transitively checks each rule file referenced by rule_files. It prints SUCCESS per file and exits non-zero if any check fails.

Common usage

Terminal

promtool check config prometheus.yml
# check config and referenced rules together
promtool check config prometheus.yml && \
  promtool check rules rules/*.yml

Options

Item	What it does
check config <file>	Validate the main config file
rule_files globs	Referenced rule files are also checked
scrape_configs	Relabel and SD config are validated
--lint / --lint-fatal	Enable and enforce lint checks

In CI

Keep prometheus.yml in the repo and gate changes on promtool check config so a broken scrape or relabel config never merges. Because it also walks rule_files, a single check covers both the config and the rules it references.

Common errors in CI

"FAILED: parsing YAML file prometheus.yml: yaml: unmarshal errors" means a wrong type or unknown key, for example a string where a list is expected. "FAILED: ... relabel configuration for replace action requires 'target_label' value" flags an invalid relabel step. "field <x> not found in type config.plain" means a misspelled config key. Any FAILED line yields a non-zero exit.