🚨 VictoriaMetrics Error: 'bind: address already in use' — Cause, Fix, and Troubleshooting Guide

Overview

Every VictoriaMetrics binary binds an HTTP listener defined by -httpListenAddr (single-node victoria-metrics defaults to :8428; vminsert :8480, vmselect :8481, vmalert :8880). If that TCP port is already held when the process starts, the bind fails and the binary exits immediately:

cannot start the server at ":8428": listen tcp :8428: bind: address already in use

This is an operating-system level conflict, not a VictoriaMetrics configuration bug — some process already owns the port. The usual cause is a second instance of the same binary, a leftover process from a previous run, or systemd starting the unit twice. The listener never comes up, so the service is fully down until the conflict is cleared.

Symptoms

• The VictoriaMetrics process exits on startup and systemd reports the unit as failed or in a restart loop.
• journalctl shows the bind: address already in use line for the configured port.
• The HTTP endpoint (for example :8428) is reachable, but served by a different or stale process than the one you just started.
• The problem appears right after a deploy, an upgrade, or a config reload that restarted the service.

Common Root Causes

• Another VictoriaMetrics instance is already running — a duplicate container or a second manual invocation holds the port.
• A port conflict with another process — an unrelated service was assigned the same port.
• A previous process did not exit — an old instance is still bound after a failed or partial restart.
• systemd double-starting the unit — two unit files, or a stray ExecStart, launch the binary twice on the same port.

How to diagnose

Find exactly which process holds the port and its PID:

ss -ltnp | grep 8428

Confirm whether it is a stray VictoriaMetrics binary and how it was started:

ps -o pid,ppid,cmd -p "$(ss -ltnp | grep 8428 | grep -oP 'pid=\K[0-9]+' | head -1)"

Check for duplicate systemd units that could both bind the port:

systemctl list-units --all | grep -iE 'victoria|vminsert|vmselect|vmalert'

Fixes

1. Find the holder with ss -ltnp | grep 8428. Identify the PID and command owning the port before killing anything, so you do not stop an unrelated service.

2. Stop the stale process. If it is an orphaned VictoriaMetrics instance, stop it via its unit or terminate the PID:

systemctl stop victoriametrics
# or, for an orphan with no unit:
kill "$(ss -ltnp | grep 8428 | grep -oP 'pid=\K[0-9]+' | head -1)"

3. Change -httpListenAddr to a free port if the port legitimately belongs to another service:

./victoria-metrics -httpListenAddr=':8528'

Update any scrapers, vmalert -datasource.url, and load balancers to the new port.

4. Ensure only one systemd unit or container maps the port. Remove duplicate unit files and confirm no container publishes the same host port; a single owner per port prevents the conflict from recurring on restart.

What to watch out for

• Do not blindly kill the PID from ss — verify it is actually the intended VictoriaMetrics process, not a different service that happens to use the port.
• In containers, address already in use often means two containers publish the same host port; check the port mappings, not just processes inside one container.
• After a crash the old process can linger in a shutdown state briefly; wait a moment and re-check ss before assuming a duplicate.
• Changing -httpListenAddr without updating every client (scrapers, vmalert, Grafana datasources) will trade this error for silent connection failures elsewhere.

Related

• VictoriaMetrics Error Guide: cannot obtain lock
• VictoriaMetrics Error Guide: vmstorage nodes unavailable
• VictoriaMetrics Error Guide: remote write connection refused