What causes "filter item key is invalid: %w" in SigNoz/signoz?

Inspect the wrapped error and fix the offending item's key (ensure Key is non-empty and type/column are valid)

filter item key is invalid: %w

Error message

filter item key is invalid: %w

What it means

Each FilterSet item's Key must pass AttributeKey.Validate(). This wraps that error, indicating one of the filter item keys has an invalid/unknown key (e.g. an empty or malformed key).

Source

Thrown at pkg/query-service/model/v3/v3.go:1195

	if f == nil {
		return nil
	}
	return &FilterSet{
		Operator: f.Operator,
		Items:    f.Items,
	}
}

func (f *FilterSet) Validate() error {
	if f == nil {
		return nil
	}
	if f.Operator != "" && f.Operator != "AND" && f.Operator != "OR" {
		return fmt.Errorf("operator must be AND or OR")
	}
	for _, item := range f.Items {
		if err := item.Key.Validate(); err != nil {
			return fmt.Errorf("filter item key is invalid: %w", err)
		}
	}
	return nil
}

// For serializing to and from db
func (f *FilterSet) Scan(src interface{}) error {
	if data, ok := src.([]byte); ok {
		return json.Unmarshal(data, &f)
	}
	return nil
}

func (f *FilterSet) Value() (driver.Value, error) {
	filterSetJson, err := json.Marshal(f)
	if err != nil {
		return nil, errors.Wrap(err, "could not serialize FilterSet to JSON")
	}

View on GitHub (pinned to 5069bf80b0)

Solutions

Inspect the wrapped error and fix the offending item's key (ensure Key is non-empty and type/column are valid)
Log the full FilterSet on validation failure to identify which item is broken

Example fix

// before
{"items":[{"key":{"key":""},"value":"x"}]}
// after
{"items":[{"key":{"key":"service.name"},"value":"x"}]}

Defensive patterns

Strategy: validation

Validate before calling

for _, it := range fs.Items { if it.Key.Key == "" { return errors.New("filter item key must not be empty") } }

Type guard

func hasValidKeys(fs v3.FilterSet) bool { for _, it := range fs.Items { if it.Key.Validate() != nil { return false } }; return true }

Try / catch

if err := query.Validate(); err != nil { if strings.Contains(err.Error(), "filter item key is invalid") { log.Printf("bad filter item: %+v", fs.Items) }; return err }

Prevention

Resolve dynamic keys to non-empty values before building filters
Log the payload when validation fails to find the bad item

When it happens

Trigger: A filters item whose Key fails Validate() — typically a key with an empty Key field, or an invalid type/column combination in the AttributeKey struct.

Common situations: Dynamically built filters where a variable key resolves to empty; migration from older filter payloads missing key metadata.

Related errors

AI-assisted analysis of SigNoz/signoz@5069bf80b0 (2026-08-28). Data as JSON: /api/errors/d990cd04320b1701. Report an issue: GitHub.