jaegertracing/jaeger · error

this storage backend requires a service name to search; sear

Error message

this storage backend requires a service name to search; searching all services is not supported

What it means

ErrServiceNameRequired is returned by FindTraces when a search omits the service name while the configured storage backend's reader cannot search without one (RFC 0013 §3.3). The message names the backend's limitation rather than a missing field because the same query is valid against other backends. The API layers deliberately map it to HTTP 400 / gRPC InvalidArgument (it satisfies querysvc.IsBadRequest) so the caller knows to change the query.

Source

Thrown at cmd/jaeger/internal/extension/jaegerquery/querysvc/service.go:32

	"go.opentelemetry.io/collector/pdata/ptrace"

	"github.com/jaegertracing/jaeger-idl/model/v1"
	expression "github.com/jaegertracing/jaeger-idl/query/expression/v1"
	"github.com/jaegertracing/jaeger/cmd/jaeger/internal/extension/jaegerquery/internal/adjuster"
	"github.com/jaegertracing/jaeger/components/extension/jaegerquery/queryinterceptor"
	"github.com/jaegertracing/jaeger/internal/jptrace"
	"github.com/jaegertracing/jaeger/internal/storage/v1/api/spanstore"
	"github.com/jaegertracing/jaeger/internal/storage/v2/api/depstore"
	"github.com/jaegertracing/jaeger/internal/storage/v2/api/tracestore"
)

var errNoArchiveSpanStorage = errors.New("archive span storage was not configured")

// ErrServiceNameRequired is returned for a search that omits the service name against a
// backend whose reader does not accept one (RFC 0013 §3.3). It names the backend's
// limitation rather than the missing field, because the same query is valid elsewhere.
// The API layers map it to InvalidArgument / HTTP 400.
var ErrServiceNameRequired = errors.New(
	"this storage backend requires a service name to search; searching all services is not supported",
)

// QueryServiceOptions holds the configuration options for the query service.
type QueryServiceOptions struct {
	// ArchiveTraceReader is used to read archived traces from the storage.
	ArchiveTraceReader tracestore.Reader
	// ArchiveTraceWriter is used to write traces to the archive storage.
	ArchiveTraceWriter tracestore.Writer
	// MaxClockSkewAdjust is the maximum duration by which to adjust a span.
	MaxClockSkewAdjust time.Duration
	// MaxTraceSize is the maximum number of spans allowed per trace. A value of 0 (default) means unlimited.
	// If a trace has more spans than this limit, it will be truncated and a warning will be added.
	MaxTraceSize int
	// Interceptors are the query-interceptor extensions this deployment configured, in the order
	// it named them. The query service invokes their OnQuery around every trace search and their
	// OnResult around every batch of loaded traces. Most deployments configure none.
	Interceptors []queryinterceptor.Interceptor

View on GitHub (pinned to 806f444784)

Solutions

1. Add a service query parameter to the search request (e.g. ?service=frontend&...).
2. Enumerate services first via the /api/services endpoint and iterate searches per service instead of searching all services at once.
3. If service-less search is a hard requirement, switch to a storage backend whose reader supports it.
4. Ensure your API client treats this as a 400-class error (querysvc.IsBadRequest) and shows an actionable message, not a retryable 500.

Example fix

// before
GET /api/traces?limit=50  // no service, backend requires one
// after
services := getServices(ctx) // GET /api/services
GET /api/traces?service=frontend&limit=50

if service == "" {
    return errors.New("this backend requires a service parameter for trace search")
}

func isServiceNameRequired(err error) bool {
    return errors.Is(err, querysvc.ErrServiceNameRequired) || querysvc.IsBadRequest(err) && strings.Contains(err.Error(), "service name")
}

err := svc.FindTraces(ctx, q, onTrace)
if err != nil {
    if errors.Is(err, querysvc.ErrServiceNameRequired) {
        return status.Error(codes.InvalidArgument, "search requires ?service=... on this backend")
    }
    return err
}

When it happens

Trigger: Calling the /api/traces search endpoint (or gRPC SpansQuery) without a `service` parameter against a backend whose reader rejects service-less searches; the service is only added by the caller, never defaulted by the service layer.

Common situations: 'Search all services' UI dashboards pointed at a backend that requires a service; scripts that browse traces by time range alone; switching storage backends (e.g. to one with this limitation) and reusing old queries that omitted service.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• please provide at least one service name
• default_search_depth must be a positive number
• max_search_depth must be a positive number
• tools[%d].name is empty or whitespace
• unable to parse param '%s': %w

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