VictoriaMetrics/VictoriaMetrics · error

failed to search metricIDs: %w

Error message

failed to search metricIDs: %w

What it means

This wraps any error from searchMetricIDs on the slow path (tag-filters cache miss) in the tag-filters-to-metricIDs lookup. All underlying index-search errors (I/O, deadline, corruption, limits) surface to the caller wrapped in this message.

Source

Thrown at lib/storage/index_db.go:1739

	tfKeyBuf := tagFiltersKeyBufPool.Get()
	defer tagFiltersKeyBufPool.Put(tfKeyBuf)

	tfKeyBuf.B = marshalTagFiltersKey(tfKeyBuf.B[:0], tfss, tr)
	metricIDs, ok := db.getMetricIDsFromTagFiltersCache(qt, tfKeyBuf.B)
	if ok {
		// Fast path - metricIDs found in the cache
		if metricIDs.Len() > maxMetrics {
			return nil, errTooManyTimeseries(maxMetrics)
		}
		return metricIDs, nil
	}

	// Slow path - search for metricIDs in the db
	is := db.getIndexSearch(deadline)
	metricIDs, err := is.searchMetricIDs(qt, tfss, tr, maxMetrics)
	db.putIndexSearch(is)
	if err != nil {
		return nil, fmt.Errorf("failed to search metricIDs: %w", err)
	}

	// Store metricIDs in the cache.
	db.putMetricIDsToTagFiltersCache(qt, metricIDs, tfKeyBuf.B)

	return metricIDs, nil
}

func (db *indexDB) wrapError(op string, err error) error {
	return fmt.Errorf("failed to %s in indexDB %q: %w", op, db.name, err)
}

// SearchTSIDs searches the TSIDs that correspond to filters within the given
// time range.
//
// The returned TSIDs are sorted.
//
// The method will fail if the number of found TSIDs exceeds maxMetrics or the

View on GitHub (pinned to 5079fb58f1)

Solutions

1. Read the wrapped cause and address it (deadline, limits, or corruption)
2. Increase -search.max* limits (maxMetrics, maxQueryDuration) if limits were hit
3. Fix storage issues (disk health, restore corrupted parts)
4. Narrow the query filters/time range to reduce scan cost

// pre-validate filters and limits before searching
if len(tfss) == 0 { return nil, nil }
if maxMetrics <= 0 { maxMetrics = defaultMaxMetrics }

metricIDs, err := db.SearchMetricIDs(qt, tfss, tr, maxMetrics, deadline)
if err != nil {
    if strings.Contains(err.Error(), "deadline") {
        // narrow time range and retry
    } else {
        return nil, fmt.Errorf("metric id lookup failed: %w", err)
    }
}

When it happens

Trigger: Calling SearchMetricIDs (used by all query APIs) when the tag-filters cache misses and the underlying index search fails: deadline exceeded, I/O error, corrupted index, or maxMetrics exceeded.

Common situations: High-cardinality queries exceeding maxMetrics; slow disks; corrupted parts; expired deadlines under heavy load.

Related errors

• error when searching for tag name prefix %q: %w
• error when searching for tag value suffixes for prefix %q: %
• more than maxPaths=%d suffixes found
• more than maxPaths=%d paths found
• error when counting unique timeseries: %w

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