🚨 VictoriaMetrics Error: 'missing -remoteWrite.url command-line flag' — Cause, Fix, and Troubleshooting Guide

Overview

vmagent scrapes targets and forwards the samples to remote storage over the Prometheus remote-write protocol. That destination is not optional: if you start vmagent without telling it where to send data, it refuses to run. The process exits immediately at startup with a fatal error:

missing -remoteWrite.url command-line flag; it must contain the url of the remote storage to send scraped data to

This is a configuration error, not a runtime failure — vmagent never gets far enough to scrape anything. It almost always shows up right after a deploy or a container/systemd unit change, where the flag was dropped, mistyped, or expanded from an empty variable.

Symptoms

• vmagent exits within a second of starting and never opens its HTTP port.
• Container orchestrators show the pod in CrashLoopBackOff with the fatal line in the logs.
• systemd reports the unit as failed with a non-zero exit status right after start.
• No scrape metrics ever appear in downstream storage because the agent never came up.
• The same image or binary worked before a recent change to the command, unit file, or environment.

Common Root Causes

• The flag was omitted entirely — the -remoteWrite.url argument is simply not present in the command line.
• An env var expanded to empty — the URL is templated from a variable (e.g. -remoteWrite.url=$RW_URL) that resolved to nothing at runtime.
• A typo in the flag name — a misspelled flag is ignored, so vmagent sees no remote-write URL at all.
• A broken container command — an entrypoint, shell wrapper, or args array split or stripped the value, leaving the flag without its URL.

How to diagnose

First look at the exact command the process was launched with. This exposes a missing flag, a typo, or an unexpanded variable at a glance:

# Container: dump the effective command and args
ps aux | grep '[v]magent'

# Or inspect the rendered command in the orchestrator/unit
systemctl cat vmagent

Confirm whether the environment variable you rely on actually holds a value in the process’s own environment:

# Inspect the running (or last-run) process environment
tr '\0' '\n' < /proc/$(pgrep -f vmagent)/environ | grep -i RW_URL

# In a container image, test expansion the same way the entrypoint would
docker run --rm your-vmagent-image sh -c 'echo "url=[$RW_URL]"'

An empty [] in that output means the variable never expanded — the flag reached vmagent with no URL attached.

Fixes

1. Set the remote-write URL explicitly. Point vmagent at your vminsert (cluster) or single-node ingestion path:

# Cluster: send to vminsert on 8480
./vmagent -promscrape.config=/etc/vmagent/scrape.yml \
  -remoteWrite.url=http://vminsert:8480/insert/0/prometheus/api/v1/write

# Single-node: send to victoria-metrics on 8428
./vmagent -promscrape.config=/etc/vmagent/scrape.yml \
  -remoteWrite.url=http://victoria-metrics:8428/api/v1/write

2. Fan out to several backends by passing -remoteWrite.url more than once — vmagent replicates to every URL:

./vmagent -promscrape.config=/etc/vmagent/scrape.yml \
  -remoteWrite.url=http://vminsert-a:8480/insert/0/prometheus/api/v1/write \
  -remoteWrite.url=http://vminsert-b:8480/insert/0/prometheus/api/v1/write

3. Verify env-var expansion in the container or systemd command. Make sure the variable is defined in the same scope that launches vmagent, and that the shell (not a literal single-quoted string) actually substitutes it:

# systemd: define it where the unit can see it
# /etc/systemd/system/vmagent.service.d/override.conf
[Service]
Environment=RW_URL=http://vminsert:8480/insert/0/prometheus/api/v1/write

4. Fix the flag name. Confirm it is spelled exactly -remoteWrite.url (camelCase, dotted url); a misspelling is silently ignored and produces this same fatal error.

What to watch out for

• The URL path matters: the cluster ingestion path is /insert/<tenant>/prometheus/api/v1/write, while single-node uses /api/v1/write — mixing them causes different, later errors.
• Single-quoting the whole command in a shell wrapper prevents variable expansion; use double quotes or let the orchestrator do the substitution.
• When passing multiple URLs, per-URL options (like -remoteWrite.urlRelabelConfig) are index-ordered — keep the URL order stable so the right config binds to the right backend.
• A wrong tenant prefix (/insert/0/...) does not fail at startup; it surfaces later as a 400 from vminsert, so validate the tenant too.

Related

• VictoriaMetrics Error Guide: unsupported path requested
• VictoriaMetrics Error Guide: remote write connection refused
• VictoriaMetrics Error Guide: missing tenant id