🚨 VictoriaMetrics Error: 'cannot load relabel configs ... unsupported relabel action' — Cause, Fix, and Troubleshooting Guide

Overview

vmagent applies relabeling in several places — -remoteWrite.relabelConfig, the global -relabelConfig, and inline relabel_configs/metric_relabel_configs inside a scrape config. Each relabel rule must use a supported action; anything else stops vmagent from loading the file at startup or reload:

cannot load relabel configs from "/etc/vmagent/relabel.yml": unsupported relabel action "dropp"; supported actions: replace, keep, drop, keep_if_equal, drop_if_equal, labelmap, labeldrop, labelkeep

The message conveniently lists every valid action. A typo (dropp for drop) is the classic trigger, but the same loader also rejects rules with a missing source_labels, a broken regex, or bad YAML indentation. vmagent refuses to start until the config parses, so this is a hard, fail-closed error.

Symptoms

• vmagent exits immediately on start, or a live reload is rejected and the old config stays active.
• The log names the exact file (/etc/vmagent/relabel.yml) and the offending action string.
• A recently edited relabel or scrape config breaks a previously healthy vmagent.
• -promscrape.config.dryRun fails with a relabel or YAML parse error.

Common Root Causes

• An unknown/misspelled action — dropp, replaces, label_map, or any value not in the supported list.
• Missing source_labels — an action like replace, keep, or drop that needs input labels but has none.
• An invalid regex — a pattern that is not valid RE2, or one written as a substring match when relabeling requires a full match.
• YAML indentation errors — a misaligned action, regex, or source_labels key that changes the document structure.

How to diagnose

Read the named file and check each rule’s action against the supported set printed in the error:

grep -nE 'action:|source_labels:|regex:' /etc/vmagent/relabel.yml

For scrape-time relabeling, dry-run the promscrape config so vmagent validates the whole file without starting the agent:

./vmagent -promscrape.config='/etc/vmagent/scrape.yml' \
  -promscrape.config.dryRun

Validate the YAML structure independently to rule out an indentation problem:

python3 -c 'import yaml,sys; yaml.safe_load(open("/etc/vmagent/relabel.yml")); print("ok")'

Fixes

1. Use only supported actions. Correct the action to one of replace, keep, drop, keep_if_equal, drop_if_equal, labelmap, labeldrop, labelkeep. For the example, dropp becomes drop:

- source_labels: [__meta_kubernetes_pod_phase]
  regex: "Succeeded|Failed"
  action: drop

2. Provide source_labels where required. Actions that match on label values (replace, keep, drop, keep_if_equal, drop_if_equal) need source_labels; labeldrop/labelkeep/labelmap operate on label names via regex instead.

3. Fix the regex — it must be a full-match RE2 pattern. Relabel regexes are anchored to the whole value, so write node_.+ rather than a bare substring, and confirm the syntax is valid RE2 (no lookaround, no backreferences).

4. Dry-run with -promscrape.config.dryRun for scrape relabeling. Wire this into CI or a pre-deploy check so a bad relabel_configs block is caught before it reaches a running vmagent.

5. Reload after fixing. Once the file parses, trigger a hot reload instead of a full restart:

curl -s -X POST 'http://localhost:8429/-/reload'

What to watch out for

• The error is fail-closed: on a bad reload vmagent keeps the previous config, so a “successful” edit may silently not be applied until you confirm the reload succeeded.
• Relabel regexes are full-match and anchored; a pattern that worked as a grep substring will silently match nothing here.
• keep_if_equal/drop_if_equal compare two source_labels to each other and take no regex; mixing them up with keep/drop is a common mistake.
• Applying an over-broad labeldrop/labelkeep can strip labels you rely on downstream; test the effect with -promscrape.config.dryRun output.

Related

• VictoriaMetrics Error Guide: high churn rate
• VictoriaMetrics Error Guide: labels count exceeds limit
• VictoriaMetrics Error Guide: kubernetes SD discovery error