crowdsecurity/crowdsec · error

filter is mandatory for non-IP, non-Range scope

Error message

filter is mandatory for non-IP, non-Range scope

What it means

Scope validation requiring an expression. For any scope that is neither 'Ip' nor 'Range' (both of which have implicit key derivation), the scope's Filter is what computes the bucket key from the event; an empty filter would make the bucket key undefined, so CompileFilter rejects it and compiles the filter to expr.

Source

Thrown at pkg/leakybucket/scopetype.go:36

func (s *ScopeType) CompileFilter() error {
	if s.Scope == types.Undefined {
		s.Scope = types.Ip
	}

	if s.Scope == types.Ip {
		if s.Filter != "" {
			return errors.New("filter is not allowed for IP scope")
		}

		return nil
	}

	if s.Scope == types.Range && s.Filter == "" {
		return nil
	}

	if s.Filter == "" {
		return errors.New("filter is mandatory for non-IP, non-Range scope")
	}

	runTimeFilter, err := compile(s.Filter, nil)
	if err != nil {
		return fmt.Errorf("error compiling the scope filter: %w", err)
	}

	s.RunTimeFilter = runTimeFilter

	return nil
}

View on GitHub (pinned to 909b515798)

Solutions

1. Add a valid expr 'expression' under the scope definition in the scenario YAML.
2. If the intent was IP-keyed bucketing, set scope type to ip (which needs no filter).
3. If the intent was range-based bucketing, set scope type to range; it also needs no filter.

Example fix

// before
scope:
  type: metadata
// after
scope:
  type: metadata
  expression: evt.Meta.target_user

if scope.Scope != types.Ip && scope.Scope != types.Range && scope.Filter == "" {
    return errors.New("non-ip/non-range scope needs an expression")
}

if err := scope.CompileFilter(); err != nil {
    return fmt.Errorf("invalid scope in scenario %s: %w", name, err)
}

When it happens

Trigger: Calling Scope.CompileFilter() where s.Scope is a custom/non-IP/non-Range type (e.g. 'metadata', 'range'-like custom scopes) and s.Filter is the empty string; also occurs when the filter is present but fails compilation, producing the wrapped 'error compiling the scope filter' variant.

Common situations: Custom scenario YAML declaring a non-ip scope without an 'expression' field, typo'ing the expression key so it parses as empty, or programmatically building a Scope struct and forgetting to set Filter before CompileFilter.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• filter is not allowed for IP scope
• non-empty filter %q was not compiled
• group_name is mandatory for CloudwatchSource
• path must start with /
• invalid filter

AI-assisted analysis of crowdsecurity/crowdsec@909b515798 (2026-09-06). Data as JSON: /api/errors/a67c7a730163c1e2. Report an issue: GitHub.