VictoriaMetrics/VictoriaMetrics · error

unexpected `match` item: %w

Error message

unexpected `match` item: %w

What it means

Wrapper inside IfExpression.unmarshalFromInterface when parsing an array-form `match` option: one list element failed newIfExpression (invalid series selector syntax for that item); the %w chain carries the selector parse error.

Source

Thrown at lib/promrelabel/if_expression.go:125

func (ie *IfExpression) unmarshalFromInterface(v any) error {
	ies := ie.ies[:0]
	switch t := v.(type) {
	case string:
		ieLocal, err := newIfExpression(t)
		if err != nil {
			return fmt.Errorf("unexpected `match` option: %w", err)
		}
		ies = append(ies, ieLocal)
	case []any:
		for _, x := range t {
			s, ok := x.(string)
			if !ok {
				return fmt.Errorf("unexpected `match` item type; got %#v; want string", x)
			}
			ieLocal, err := newIfExpression(s)
			if err != nil {
				return fmt.Errorf("unexpected `match` item: %w", err)
			}
			ies = append(ies, ieLocal)
		}
	default:
		return fmt.Errorf("unexpected `match` type; got %#v; want string or an array of strings", t)
	}
	ie.ies = ies
	return nil
}

// MarshalYAML marshals ie to YAML
func (ie *IfExpression) MarshalYAML() (any, error) {
	if ie == nil || len(ie.ies) == 0 {
		return nil, nil
	}
	if len(ie.ies) == 1 {
		return ie.ies[0].MarshalYAML()
	}

View on GitHub (pinned to 5079fb58f1)

Solutions

1. Locate the failing item from the wrapped %w error text (it contains the parse error) and fix its syntax
2. Make each item a bare series selector `[name[{k="v",...}]]`
3. Quote each item with single quotes so `{`, `}`, and `"` survive YAML parsing
4. Test each selector individually with metricsql/promtool before deploying

Example fix

// before
match:
  - '{job="a"}'
  - 'job=b{'
// after
match:
  - '{job="a"}'
  - '{job="b"}'

import "github.com/VictoriaMetrics/metricsql"

func validateMatchList(items []string) error {
	for _, s := range items {
		if _, err := metricsql.Parse(s); err != nil {
			return fmt.Errorf("invalid match item %q: %w", s, err)
		}
	}
	return nil
}

if err := yaml.Unmarshal(data, &cfg); err != nil {
	if strings.Contains(err.Error(), "unexpected `match` item") {
		return fmt.Errorf("one `match` list entry is not a valid selector: %w", err)
	}
	return err
}

When it happens

Trigger: `match` is an array of strings but at least one element is an invalid selector, e.g. `match: ['{job="a"}', 'bad{']`.

Common situations: Copy-paste typos in one element of a multi-selector list; unbalanced braces from YAML quoting; selectors containing unescaped characters; using PromQL expressions instead of selectors in one item.

Related errors

• unexpected `match` option: %w
• cannot parse series selector: %w
• expecting series selector; got %q
• cannot unmarshal `match` option: %w
• unexpected `match` item type; got %#v; want string

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