extension %q does not implement queryinterceptor.Interceptor

Error message

extension %q does not implement queryinterceptor.Interceptor

What it means

The requested extension ID was found in the host, but its component does not implement the queryinterceptor.Interceptor interface (type assertion comp.(pub.Interceptor) fails). Only extensions purpose-built as Jaeger query interceptors can be listed in the jaeger_query interceptor config; arbitrary extensions (e.g. health_check, pprof) cannot.

Source

Thrown at cmd/jaeger/internal/extension/jaegerquery/queryinterceptor/resolver.go:47

// component references an extension by component.ID in its config and resolves
// it from host.GetExtensions() at start time.
func Resolve(host component.Host, ids []component.ID) ([]pub.Interceptor, error) {
	if len(ids) == 0 {
		return nil, nil
	}
	extensions := host.GetExtensions()
	interceptors := make([]pub.Interceptor, 0, len(ids))
	for _, id := range ids {
		comp, ok := extensions[id]
		if !ok {
			return nil, fmt.Errorf(
				"cannot find query interceptor extension %q (make sure it is defined under extensions: and enabled in service.extensions)",
				id,
			)
		}
		interceptor, ok := comp.(pub.Interceptor)
		if !ok {
			return nil, fmt.Errorf("extension %q does not implement queryinterceptor.Interceptor", id)
		}
		interceptors = append(interceptors, interceptor)
	}
	return interceptors, nil
}

View on GitHub (pinned to 806f444784)

Solutions

Replace the configured ID with one that actually implements queryinterceptor.Interceptor.
Remove the entry from jaeger_query's interceptor list if you don't need interception.
If you wrote a custom extension, add the Interceptor interface methods (e.g. the interceptor hook signatures) to its component.
Check the extension's documentation/version to confirm it is a query interceptor.

Example fix

// before
service:
  extensions: [health_check, jaeger_query]
jaeger_query:
  interceptors: [health_check]
// after
jaeger_query:
  interceptors: [my_custom_query_interceptor]

Defensive patterns

Strategy: type-guard

Validate before calling

// before listing an extension as interceptor, confirm it advertises Interceptor support in its docs/README

Type guard

func asQueryInterceptor(c component.Component) (pub.Interceptor, bool) {
    it, ok := c.(pub.Interceptor)
    return it, ok
}

Try / catch

interceptors, err := resolver.Resolve(host, ids)
if err != nil && strings.Contains(err.Error(), "does not implement") {
    log.Fatalf("config error: %v", err) // fix config, not runtime
}

Prevention

Only configure extensions documented as query interceptors.
Add a startup assertion test asserting your extension implements pub.Interceptor.
Pin extension versions compatible with your jaeger-query version.

When it happens

Trigger: queryinterceptor.Resolve with an ID that maps to an existing extension whose type lacks the Interceptor interface methods — e.g. listing `health_check` or a storage extension in jaeger_query's interceptor list.

Common situations: Misunderstanding which extensions qualify as query interceptors; wiring a generic collector extension where a Jaeger-specific interceptor is required; version mismatch where a custom interceptor extension was replaced by an incompatible one.

Related errors

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