🚨 VictoriaMetrics Error: 'the requested time range duration exceeds -search.maxExportDuration' — Cause, Fix, and Troubleshooting Guide

Overview

The /api/v1/export endpoints stream raw samples out of VictoriaMetrics. To stop a single export from pulling an unbounded amount of data, vmselect (or single-node victoria-metrics) caps the export window with -search.maxExportDuration (default 720h, i.e. 30 days). Ask for a wider range and the request is refused:

cannot export data: the requested time range duration exceeds -search.maxExportDuration=720h0m0s; narrow the time range or increase -search.maxExportDuration

This is a guard on the duration of the requested window, not on the number of samples. It fires before streaming begins, so you get a clean error rather than a partial dump. It most often appears when people try to use /export as a backup mechanism or to move a long history in one shot.

Symptoms

• A call to /api/v1/export returns the error immediately instead of streaming data.
• Bulk-migration or “dump everything” scripts fail on the first request while short-range exports succeed.
• The same export works for a 2-week window but fails once the range crosses 30 days.
• vmselect logs the cannot export data ... exceeds -search.maxExportDuration line at the time of the request.
• High-cardinality metrics over a long range trip the limit even when the calendar range looks modest.

Common Root Causes

• The export window is wider than the limit — start..end spans more than -search.maxExportDuration.
• Using /export for full backups — treating the export endpoint as a backup tool means requesting the entire retention at once.
• Very high cardinality over a long range — a long window combined with many series makes the requested duration itself the blocker before any streaming happens.

How to diagnose

Confirm the configured ceiling and the span you actually requested:

# What limit is in effect?
ps aux | grep -E '[v]mselect|[v]ictoria-metrics' | grep -oE '\-search.maxExportDuration[^ ]*'

Compute the duration of your start/end — anything over the printed limit (720h by default) will be rejected before the first byte:

# Example: this window is 60 days = 1440h, which exceeds 720h
curl -s -G 'http://localhost:8481/select/0/prometheus/api/v1/export' \
  --data-urlencode 'match[]={__name__=~"node_.+"}' \
  --data-urlencode 'start=2026-05-01T00:00:00Z' \
  --data-urlencode 'end=2026-06-30T00:00:00Z' -o /dev/null -w '%{http_code}\n'

Fixes

1. Split the export into smaller time chunks. Loop over sub-windows that each stay under the limit and concatenate the output:

# Export one 7-day chunk at a time, staying well under 720h
for wk in 0 1 2 3; do
  start=$(date -u -d "2026-05-01 +$((wk*7)) days" +%Y-%m-%dT00:00:00Z)
  end=$(date -u -d "2026-05-01 +$(((wk+1)*7)) days" +%Y-%m-%dT00:00:00Z)
  curl -s -G 'http://localhost:8481/select/0/prometheus/api/v1/export' \
    --data-urlencode 'match[]={__name__=~"node_.+"}' \
    --data-urlencode "start=$start" --data-urlencode "end=$end" \
    >> export-part-"$wk".ndjson
done

2. Raise -search.maxExportDuration only if you genuinely need one long export in a single call:

./vmselect -storageNode=vmstorage-1:8401,vmstorage-2:8401 \
  -search.maxExportDuration=2160h   # 90 days

3. Prefer /api/v1/export/native for bulk transfer. The native format is more compact and faster for moving data between VictoriaMetrics instances:

curl -s -G 'http://localhost:8481/select/0/prometheus/api/v1/export/native' \
  --data-urlencode 'match[]={__name__=~".+"}' \
  --data-urlencode 'start=-7d' > dump.native

4. Use vmbackup/vmrestore for real backups. Exports are for data extraction, not disaster recovery. Snapshot-based backup avoids the duration limit entirely and captures a consistent copy:

./vmbackup -storageDataPath=/var/lib/victoria-metrics \
  -snapshotName=<snapshot> -dst=s3://backups/vm/

What to watch out for

• Raising the limit lets a single request stream far more data — size it against vmselect memory and the client’s ability to consume the stream.
• Chunked exports must not overlap or gap at the boundaries; align each chunk’s end to the next chunk’s start.
• /export is not a backup: it does not capture a consistent point-in-time snapshot the way vmbackup does.
• Native export and JSON export are not interchangeable formats — restore/import with the matching endpoint (/import/native for native dumps).

Related

• VictoriaMetrics Error Guide: too many points
• VictoriaMetrics Error Guide: max samples per query
• VictoriaMetrics Error Guide: cannot create snapshot