jaegertracing/jaeger · error

the structured query filter is disabled

Error message

the structured query filter is disabled

What it means

ErrFilterDisabled is returned when a trace search carries a structured query filter (RFC 0005) but the deployment has not enabled the StructuredFiltersGate feature gate. The service refuses the query instead of silently dropping the filter, because ignoring a predicate would return every trace in the time range — a dangerously different answer. It is classified as a bad request: the caller must change the query or the operator must enable the gate.

Source

Thrown at cmd/jaeger/internal/extension/jaegerquery/querysvc/filter.go:37

// separate switch, named jaeger.<backend>.structuredFilters — this gate's leaf with the backend
// in place of "query" — because the two stabilize on different schedules.
var StructuredFiltersGate = featuregate.GlobalRegistry().MustRegister(
	"jaeger.query.structuredFilters",
	featuregate.StageAlpha,
	featuregate.WithRegisterFromVersion("v2.21.0"),
	featuregate.WithRegisterDescription(
		"Accepts the RFC 0005 structured query filter on trace search. The filter AST is not yet "+
			"stable, so a query that carries one is refused while this is disabled. This admits "+
			"filters into the query path only; whether a storage backend evaluates one natively is "+
			"gated separately, by jaeger.<backend>.structuredFilters.",
	),
	featuregate.WithRegisterReferenceURL("https://github.com/jaegertracing/jaeger/blob/main/docs/rfc/0005-structured-query-filters.md"),
)

// ErrFilterDisabled is returned for a query carrying a filter to a deployment that has not
// enabled StructuredFiltersGate. The query is refused rather than served with the filter
// ignored, because dropping a predicate would answer with every trace in the time range.
var ErrFilterDisabled = errors.New("the structured query filter is disabled")

// IsBadRequest reports whether err means the caller must change the query, either
// because its shape is wrong or because this deployment's storage cannot serve it.
// Either way it is the caller's problem, so the API layers answer InvalidArgument /
// HTTP 400 rather than reporting a server fault.
func IsBadRequest(err error) bool {
	return errors.Is(err, ErrServiceNameRequired) ||
		errors.Is(err, ErrFilterDisabled) ||
		errors.Is(err, tracestore.ErrFilterUnsupported) ||
		errors.Is(err, tracestore.ErrFilterInvalid)
}

View on GitHub (pinned to 806f444784)

Solutions

1. Enable the structured-filters feature gate on the jaegerquery server (e.g. --query.feature-gates=structuredFilters or the equivalent config entry).
2. If the gate cannot be enabled, rewrite the search to use legacy tag matching or plain query parameters instead of the structured filter syntax.
3. Check querysvc.IsBadRequest handling in your API layer so this surfaces as HTTP 400 / gRPC InvalidArgument with a clear message rather than a 500.

Example fix

// before: server started without the gate
jaeger-query --span-storage.type=elasticsearch
// after: enable the gate for structured filter support
jaeger-query --span-storage.type=elasticsearch --query.feature-gates=structuredFilters

if !gateEnabled("structuredFilters") && hasStructuredFilter(query) {
    // strip the filter or rewrite to legacy tag matching before sending
    query.Filter = nil
}

func isFilterDisabled(err error) bool { return errors.Is(err, querysvc.ErrFilterDisabled) }

if err := svc.FindTraces(ctx, q, onTrace); err != nil {
    if errors.Is(err, querysvc.ErrFilterDisabled) {
        // 400 for the user: retry without filter or tell them to enable the gate
        return status.Error(codes.InvalidArgument, err.Error())
    }
    return err
}

When it happens

Trigger: Sending a search whose TraceQueryParams include structured filter predicates (e.g. tag/attribute filters via the JSON query filter syntax) to a jaegerquery instance started without the structured-filters feature gate enabled.

Common situations: A client library upgraded to use structured filters while the server runs an older/default configuration; an operator rolling out RFC 0005 support without flipping the feature gate; staging environments where the gate is on but production is not.

Related errors

• %w: enable the %q feature gate to use it
• deprecated ES rotation flags (%s) are no longer supported; m
• file must begin with '['
• only one of basic auth (--es.username/--es.password), --es.t
• wrong number of arguments

AI-assisted analysis of jaegertracing/jaeger@806f444784 (2026-09-01). Data as JSON: /api/errors/5c8d9d743129e23a. Report an issue: GitHub.