{"record":{"id":"164c329ebbe978f2","repo":"jaegertracing/jaeger","slug":"api-v3-does-not-expose-the-backend-s-search-capabi","errorCode":null,"errorMessage":"api_v3 does not expose the backend's search capabilities: %w","messagePattern":"api_v3 does not expose the backend's search capabilities: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"cmd/jaeger/internal/integration/trace_reader.go","lineNumber":50,"sourceCode":"\nvar (\n\t_ tracestore.Reader = (*traceReader)(nil)\n\t_ io.Closer         = (*traceReader)(nil)\n)\n\n// traceReader retrieves trace data from the jaeger-v2 query service through the api_v2.QueryServiceClient.\ntype traceReader struct {\n\tlogger     *zap.Logger\n\tclientConn *grpc.ClientConn\n\tclient     api_v3.QueryServiceClient\n}\n\n// SearchCapabilities cannot be answered: api_v3 has no capability discovery, so this\n// client has no way to ask the query service what the storage behind it supports\n// (RFC 0013 §3.7 proposes the API that would let it). Reporting ErrUnsupported says\n// exactly that, where any concrete value would be a guess a caller might trust.\nfunc (*traceReader) SearchCapabilities(context.Context) (tracestore.SearchCapabilities, error) {\n\treturn tracestore.SearchCapabilities{}, fmt.Errorf(\n\t\t\"api_v3 does not expose the backend's search capabilities: %w\", errors.ErrUnsupported,\n\t)\n}\n\nfunc createTraceReader(logger *zap.Logger, port int) (*traceReader, error) {\n\tlogger.Info(\"Creating the trace reader\", zap.Int(\"port\", port))\n\topts := []grpc.DialOption{\n\t\tgrpc.WithTransportCredentials(insecure.NewCredentials()),\n\t}\n\n\tcc, err := grpc.NewClient(ports.PortToHostPort(port), opts...)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn &traceReader{\n\t\tlogger:     logger,\n\t\tclientConn: cc,","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/jaegertracing/jaeger/blob/806f4447841ecdb60519f408b004a599d515f437/cmd/jaeger/internal/integration/trace_reader.go#L32-L68","documentation":"traceReader.SearchCapabilities must report what search predicates the underlying storage supports, but api_v3 has no capability-discovery RPC, so the client cannot learn what the remote query service supports. Rather than guess, it returns the zero tracestore.SearchCapabilities wrapped with errors.ErrUnsupported and the message 'api_v3 does not expose the backend's search capabilities'.","triggerScenarios":"Any call to SearchCapabilities on the api_v3-based traceReader (used by e2e integration tests driving jaeger over the wire) — unconditionally returns this error.","commonSituations":"Test frameworks or code probing search capabilities of a remote jaeger reached through api_v3; capability-adaptive callers that skip unsupported predicates will always take their 'unsupported' path with this backend.","solutions":["Treat errors.ErrUnsupported as expected for api_v3 and use conservative/default search behavior","Use a native tracestore Reader (e.g. direct storage backend) instead of the api_v3 remote reader if capabilities matter","Adopt the capability-discovery API proposed in RFC 0013 §3.7 once available"],"exampleFix":"// before\ncaps, err := reader.SearchCapabilities(ctx)\nif err != nil { return err }\n// after\ncaps, err := reader.SearchCapabilities(ctx)\nif errors.Is(err, errors.ErrUnsupported) {\n    caps = tracestore.SearchCapabilities{} // assume minimal support\n} else if err != nil { return err }","handlingStrategy":"fallback","validationCode":"// capability probe\ncaps, err := reader.SearchCapabilities(ctx)\nsupportsMaxDuration := err == nil && caps.MaxDuration","typeGuard":null,"tryCatchPattern":"caps, err := reader.SearchCapabilities(ctx)\nswitch {\ncase err == nil:\n    useCaps(caps)\ncase errors.Is(err, errors.ErrUnsupported): // api_v3 reader\n    useCaps(tracestore.SearchCapabilities{}) // conservative defaults\ndefault:\n    return err\n}","preventionTips":["Never assume capability discovery exists for remote api_v3 backends","Design callers to accept zero-value capabilities meaningfully","Track RFC 0013 for a real capability API and migrate when available"],"tags":["api-v3","search-capabilities","unsupported"],"backgroundTag":"capability-discovery-unsupported","analyzedSha":"806f4447841ecdb60519f408b004a599d515f437","analyzedAt":"2026-09-01T02:39:22.140Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}