🚨 VictoriaMetrics Error: 'unsupported path requested' — Cause, Fix, and Troubleshooting Guide

Overview

In cluster mode, VictoriaMetrics splits responsibilities across components — vminsert for writes, vmselect for reads, vmstorage for storage — and each exposes only the routes it owns, under a tenant-scoped path prefix. When a request hits a component on a path it does not serve, or without the required tenant prefix, the HTTP router rejects it:

unsupported path requested: "/api/v1/write"; make sure the request is sent to the correct component and includes the tenant prefix

The single-node binary accepts bare paths like /api/v1/write, but the cluster does not. Cluster URLs must name the operation namespace and tenant: /insert/<tenant>/... on vminsert and /select/<tenant>/... on vmselect. This error almost always means a client was pointed at the wrong component, the wrong port, or was migrated from single-node without updating its paths.

Symptoms

• A remote-write client (vmagent, Prometheus, Telegraf) gets unsupported path requested: "/api/v1/write" from the cluster.
• Grafana or an API client fails to query with the same “unsupported path” message on the read side.
• Ingestion or queries that worked against a single-node instance break after moving to the cluster.
• The URL is missing the /insert/<tenant>/ or /select/<tenant>/ prefix, or points at the wrong port.
• A write is accidentally aimed at vmselect (or a read at vminsert), so the target component has no such route.

Common Root Causes

• Wrong component or port — writing to vmselect 8481 instead of vminsert 8480, or reading from vminsert instead of vmselect 8481.
• Missing tenant prefix — using bare /api/v1/write or /api/v1/query instead of the cluster’s /insert/<tenant>/... or /select/<tenant>/....
• Single-node path against the cluster — a client migrated from victoria-metrics (single-node) still uses single-node URLs the cluster does not expose.
• URL typo — a misspelled namespace, a dropped tenant segment, or a wrong prometheus sub-path.

How to diagnose

Confirm which component is actually listening on the port you are hitting:

# vminsert should own 8480 (writes), vmselect 8481 (reads)
curl -s 'http://localhost:8480/metrics' | grep -m1 vm_app_version
curl -s 'http://localhost:8481/metrics' | grep -m1 vm_app_version

Send a correctly-prefixed request for tenant 0 and check it is accepted:

# Write path: vminsert 8480, /insert/<tenant>/prometheus/api/v1/write
printf 'up 1\n' | curl -s --data-binary @- \
  'http://localhost:8480/insert/0/prometheus/api/v1/import/prometheus'

# Read path: vmselect 8481, /select/<tenant>/prometheus/api/v1/query
curl -s 'http://localhost:8481/select/0/prometheus/api/v1/query?query=up'

If the prefixed URLs work but the client’s URL does not, compare them segment by segment — the mismatch is the component, the port, or the missing tenant.

Fixes

1. Write to vminsert with the insert prefix. Point remote-write at vminsert on 8480 using the tenant-scoped write path:

./vmagent \
  -remoteWrite.url=http://vminsert:8480/insert/0/prometheus/api/v1/write

2. Read from vmselect with the select prefix. Point Grafana and API clients at vmselect on 8481 using the tenant-scoped query path:

# Grafana Prometheus data source URL
http://vmselect:8481/select/0/prometheus

3. Include the numeric tenant. The <tenant> segment is the numeric accountID (or accountID:projectID for project isolation), e.g. /insert/42/... or /select/42:7/.... Use the real tenant id, not a name.

4. Verify port-to-component mapping. Double-check each client hits the component that owns its route: writes -> vminsert 8480, reads -> vmselect 8481. Do not carry single-node paths (bare /api/v1/write) into the cluster.

What to watch out for

• The cluster and single-node URL schemes differ — a migration that keeps single-node paths will fail on every request until the prefixes are added.
• Sending a write to vmselect or a read to vminsert produces this same “unsupported path” error; the route only exists on the component that owns it.
• The tenant segment is mandatory in cluster mode even for the default tenant 0 — omitting it triggers the error.
• Watch for a trailing/sub-path mismatch (/prometheus/api/v1/...); a dropped prometheus segment looks like an unsupported path too.

Related

• VictoriaMetrics Error Guide: missing tenant id
• VictoriaMetrics Error Guide: vmstorage nodes unavailable
• VictoriaMetrics Error Guide: remote write connection refused