VictoriaMetrics/VictoriaMetrics · error

duration %q must be in the range [%s, %s]

Error message

duration %q must be in the range [%s, %s]

What it means

lib/timeutil.ParseDuration wraps metricsql.DurationValue parsing and additionally bounds the result to the representable time.Duration range: milliseconds between minValidMilli (math.MinInt64/1e6) and maxValidMilli (math.MaxInt64/1e6), i.e. roughly -292 years .. 292 years. Durations outside that range are rejected with this error.

Source

Thrown at lib/timeutil/duration.go:22

	"fmt"
	"time"

	"github.com/VictoriaMetrics/metricsql"
)

var (
	minDuration = time.Duration(minValidMilli * time.Millisecond)
	maxDuration = time.Duration(maxValidMilli * time.Millisecond)
)

// ParseDuration parses duration string in Prometheus format
func ParseDuration(s string) (time.Duration, error) {
	ms, err := metricsql.DurationValue(s, 0)
	if err != nil {
		return 0, err
	}
	if ms < minValidMilli || maxValidMilli < ms {
		return 0, fmt.Errorf("duration %q must be in the range [%s, %s]", s, minDuration, maxDuration)
	}
	return time.Duration(ms) * time.Millisecond, nil
}

View on GitHub (pinned to 5079fb58f1)

Solutions

1. Lower the duration to within the supported range (about ±292 years), e.g. use `100y` instead of `1000000y`
2. Check the unit suffix: metricsql accepts s, m, h, d, w, y, i — make sure you did not double-scale the number
3. Validate flag values before launch; the error message echoes the invalid input

Example fix

// before
ParseDuration("100000000000y")
// after
ParseDuration("100y")

const maxDur = time.Duration(math.MaxInt64/1_000_000) * time.Millisecond
func safeDuration(s string) (time.Duration, error) {
	d, err := timeutil.ParseDuration(s)
	if err != nil {
		return 0, err
	}
	if d > maxDur || d < -maxDur {
		return 0, fmt.Errorf("duration %s out of range", s)
	}
	return d, nil
}

d, err := timeutil.ParseDuration(flagValue)
if err != nil {
	return fmt.Errorf("invalid duration flag %q: %w", flagValue, err)
}

When it happens

Trigger: Calling timeutil.ParseDuration with an oversized duration string such as `"100000000000y"` or an extremely large nanosecond/millisecond value (e.g. `-retentionPeriod 99999999999i`), where ms falls outside [minValidMilli, maxValidMilli].

Common situations: Unit mistakes (entering milliseconds where days were intended); misconfigured retention/dedup/scroll flags like -retentionPeriod or -streamAggr.keepMetricNames intervals set absurdly high; template substitution injecting a bad number.

Related errors

• unexpected number of items in authToken %q; got %d; want 1 o
• cannot parse hour from timezone offset %q: %w
• cannot parse minute from timezone offset %q: %w
• cannot parse accountID from %q: %w
• cannot parse projectID from %q: %w

AI-assisted analysis of VictoriaMetrics/VictoriaMetrics@5079fb58f1 (2026-09-03). Data as JSON: /api/errors/e59c874b5287aad6. Report an issue: GitHub.