🚨 VictoriaMetrics Error: 'cannot load -promscrape.config' — Cause, Fix, and Troubleshooting Guide

Overview

vmagent reads its scrape targets from the file named by -promscrape.config. It parses that file as YAML and unmarshals it into a ScrapeConfig structure at startup and on reload. If the YAML is malformed — or contains a field the parser does not recognize — vmagent refuses to start (or refuses to apply the reload) and logs:

cannot load -promscrape.config="/etc/vmagent/scrape.yml": cannot unmarshal data into ScrapeConfig: yaml: line 14: did not find expected key

The yaml: line N suffix is the important part: the YAML library gave up at a specific line because the structure there is not valid. This is almost always an indentation slip, a stray character, or an unknown/misspelled key rather than anything about VictoriaMetrics itself. Because vmagent will not run with an unparseable config, catching this before rollout keeps scraping from going dark.

Symptoms

• vmagent exits at startup with cannot load -promscrape.config=...: did not find expected key.
• A POST /-/reload or SIGHUP is rejected and the old config stays active (or vmagent crashes on restart).
• The error names a specific yaml: line N, often near a relabel_configs block or a service-discovery section.
• Scrape targets disappear from http://localhost:8429/targets after a config change.
• The file looks fine at a glance but has mixed tabs/spaces or a subtly misaligned key.

Common Root Causes

• YAML indentation or syntax error — a tab instead of spaces, a missing colon, or a misaligned list item, producing “did not find expected key”.
• Unknown or misspelled field — a key that is not part of ScrapeConfig (typo like scrap_interval, or a Prometheus field VictoriaMetrics does not accept there).
• Bad regex in relabel_configs — an invalid or unescaped regular expression inside a relabel/metric-relabel rule.
• Malformed service-discovery block — a kubernetes_sd_configs, static_configs, or similar section with wrong or misplaced keys.

How to diagnose

First confirm whether the file is even valid YAML, independent of vmagent’s schema:

# Pure YAML syntax check — catches indentation and structure errors
python3 -c 'import sys,yaml; yaml.safe_load(open("/etc/vmagent/scrape.yml"))'

Then let vmagent validate the config against its own schema without starting to scrape:

# Parse and validate the scrape config, then exit
./vmagent -promscrape.config=/etc/vmagent/scrape.yml \
  -promscrape.config.dryRun

The dry run reports the exact section it rejects. If the file parses as YAML but vmagent still complains, the problem is a schema-level issue (an unknown key or a bad regex) rather than raw syntax — jump to that block.

Fixes

1. Fix the reported line. Go to the yaml: line N from the error and correct the indentation or missing key. Use two-space indentation consistently and never mix tabs and spaces.

2. Dry-run before every rollout. Gate config changes on -promscrape.config.dryRun so a broken file is caught in CI or on the box before it takes vmagent down:

./vmagent -promscrape.config=/etc/vmagent/scrape.yml -promscrape.config.dryRun && echo OK

3. Locate an unknown field with relaxed parsing. If the syntax is valid but a field is rejected, temporarily loosen strict parsing so vmagent tells you which key it could not place, then remove or rename it:

./vmagent -promscrape.config=/etc/vmagent/scrape.yml \
  -promscrape.config.strictParse=false

Treat this as a diagnostic step, not a permanent setting — put strictParse back on once the offending field is fixed.

4. Reload cleanly once fixed. Apply the corrected config without a full restart by sending a reload signal:

# Either signal the process...
kill -HUP "$(pgrep -f 'vmagent .*-promscrape.config')"
# ...or hit the reload endpoint
curl -s -X POST 'http://localhost:8429/-/reload'

What to watch out for

• “did not find expected key” is a YAML-structure error, not a VictoriaMetrics bug — check indentation and colons at the named line first.
• Leaving -promscrape.config.strictParse=false on permanently silences useful warnings about unknown fields; use it only to hunt the bad key.
• A bad regex inside relabel_configs fails the whole config load, so one typo can stop all scraping — validate relabel rules carefully.
• After a successful reload, verify http://localhost:8429/targets actually shows the expected targets; a parse-clean config can still have an empty or wrong target set.

Related

• VictoriaMetrics Error Guide: promscrape maxScrapeSize
• VictoriaMetrics Error Guide: cannot parse MetricsQL
• VictoriaMetrics Error Guide: remote write connection refused