promtool "check config" FAILED in CI

By Daniel Zoghalchali·Latchkey

promtool check config validates prometheus.yml and every file it references; when a field is unknown, a scrape config is malformed, or a referenced rule file is missing or invalid, it prints FAILED and exits non-zero.

What this error means

A promtool check config prometheus.yml step reports "FAILED: ... error" naming an unknown field, a bad target, or a missing rule file, and the job exits 1.

Checking prometheus.yml
  FAILED: parsing YAML file prometheus.yml: yaml: unmarshal errors:
  line 12: field scrape_intervals not found in type config.GlobalConfig

Common causes

An unknown or misspelled config field

A typo like scrape_intervals instead of scrape_interval fails strict unmarshalling, so the whole config is rejected.

A referenced rule or file is missing or invalid

A rule_files glob that matches nothing valid, or a broken target file, causes the config check to fail even if the top-level YAML is fine.

How to fix it

Correct the field the error names

1. Read the line and field name in the FAILED message.
2. Fix the typo or restructure the offending block.
3. Re-run promtool check config until it reports SUCCESS.

promtool check config prometheus.yml

Check referenced rule files too

Validate the rule files the config points at so a bad rule does not surface only at load time.

promtool check config prometheus.yml && promtool check rules rules/*.yml

How to prevent it

• Gate config changes with promtool check config in CI.
• Match field names exactly to the Prometheus config schema.
• Validate referenced rule files in the same step.

Frequently asked questions

Related guides

References

• GitHub Actions documentation