crowdsecurity/crowdsec · error · InvalidFilter

filter parameter '%s' is unknown (=%s): %w

Error message

filter parameter '%s' is unknown (=%s): %w

What it means

Returned by alertPredicatesFromFilter when a filter parameter in the query string is not in the switch's known list. It names the unknown parameter and its value, wrapping the InvalidFilter sentinel, so callers know exactly which key was rejected.

Source

Thrown at pkg/database/alertfilter.go:251

			}

			if hasActiveDecision {
				predicates = append(predicates, alert.HasDecisionsWith(decision.UntilGTE(time.Now().UTC())))
			} else {
				predicates = append(predicates, alert.Not(alert.HasDecisions()))
			}
		case "kind":
			predicates = append(predicates, alert.KindEQ(value[0]))
		case "limit":
			continue
		case "sort":
			continue
		case "simulated":
			continue
		case "with_decisions":
			continue
		default:
			return nil, fmt.Errorf("filter parameter '%s' is unknown (=%s): %w", param, value[0], InvalidFilter)
		}
	}

	if err := handleAlertIPPredicates(rng, contains, &predicates); err != nil {
		return nil, err
	}

	return predicates, nil
}

func applyAlertFilter(alerts *ent.AlertQuery, filter map[string][]string) (*ent.AlertQuery, error) {
	preds, err := alertPredicatesFromFilter(filter)
	if err != nil {
		return nil, err
	}

	return alerts.Where(preds...), nil
}

View on GitHub (pinned to 909b515798)

Solutions

1. Check the LAPI swagger (pkg/models/localapi_swagger.yaml) for the accepted filter keys and rename the parameter accordingly.
2. Use cscli or an up-to-date SDK instead of hand-built query strings.
3. If your client uses a removed parameter, migrate to the current equivalent (e.g. scope/value pairs for IP filters).
4. Consult the API docs for the exact parameter names: since, until, scope, value, scenario, origin, contains, has_active_decision, include_capi, simulated, with_decisions, etc.

Example fix

// before
GET /v1/alerts?ip=1.2.3.4
// after
GET /v1/alerts?scope=ip&value=1.2.3.4

var validParams = map[string]bool{"since":true,"until":true,"scope":true,"value":true,"scenario":true,"contains":true,"has_active_decision":true,"include_capi":true,"simulated":true,"with_decisions":true}
for k := range params {
    if !validParams[k] {
        return fmt.Errorf("unknown filter param %q", k)
    }
}

resp, err := client.Alerts.List(ctx, opts)
var apiErr *crowdsec.ApiErrorResponse
if err != nil && errors.As(err, &apiErr) {
    if strings.Contains(*apiErr.Message, "is unknown") {
        // log the rejected param name from the message and fix the caller
    }
}

When it happens

Trigger: LAPI alerts list/delete request includes a query param not handled by the switch (e.g. ?ip=1.2.3.4 instead of ?scope=ip&value=1.2.3.4, or a typo like sincee=).

Common situations: Outdated clients using removed/renamed filter keys after a crowdsec upgrade, typos in hand-written API calls, custom scripts guessing parameter names.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

Related errors

• invalid contains value: %w: %w
• '%s' is not a boolean: %w: %w
• no listen_uri or listen_socket specified
• no API client section in configuration
• missing token value for api.server.auto_register

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