jaegertracing/jaeger · error

service Name must be set

Error message

service Name must be set

What it means

ErrServiceNameNotSet is returned by validateQuery in the Cassandra span reader when FindTraceIDs/FindTraces is called with a TraceQueryParams whose ServiceName is empty. Every search index is keyed by service name, so a query without one would scan an empty partition key and return zero rows indistinguishable from 'no traces'. The reader refuses the query instead; note it is wrapped with errors.ErrUnsupported since RFC 0013 §3.3.

Source

Thrown at internal/storage/v1/cassandra/spanstore/reader.go:66

		FROM service_operation_index
		WHERE service_name = ? AND operation_name = ? AND start_time > ? AND start_time < ?
		ORDER BY start_time DESC
		LIMIT ?`
	queryByDuration = `
		SELECT trace_id
		FROM duration_index
		WHERE bucket = ? AND service_name = ? AND operation_name = ? AND duration >= ? AND duration <= ?
		LIMIT ?`

	defaultNumTraces = 100
	// limitMultiple exists because many spans that are returned from indices can have the same trace, limitMultiple increases
	// the number of responses from the index, so we can respect the user's limit value they provided.
	limitMultiple = 3
)

var (
	// ErrServiceNameNotSet occurs when attempting to query with an empty service name
	ErrServiceNameNotSet = errors.New("service Name must be set")

	// ErrStartTimeMinGreaterThanMax occurs when start time min is above start time max
	ErrStartTimeMinGreaterThanMax = errors.New("start Time Minimum is above Maximum")

	// ErrDurationMinGreaterThanMax occurs when duration min is above duration max
	ErrDurationMinGreaterThanMax = errors.New("duration Minimum is above Maximum")

	// ErrMalformedRequestObject occurs when a request object is nil
	ErrMalformedRequestObject = errors.New("malformed request object")

	// ErrDurationAndTagQueryNotSupported occurs when duration and tags are both set
	ErrDurationAndTagQueryNotSupported = errors.New("cannot query for duration and tags simultaneously")

	// ErrStartAndEndTimeNotSet occurs when start time and end time are not set
	ErrStartAndEndTimeNotSet = errors.New("start and End Time must be set")
)

type serviceNamesReader func() ([]string, error)

View on GitHub (pinned to 806f444784)

Solutions

1. Set ServiceName on the TraceQueryParams before calling FindTraces/FindTraceIDs.
2. Validate the incoming query at the API boundary and reject requests with an empty service name with a clear client-facing message.
3. If 'all services' search is intended, use the dedicated service/operation listing APIs (GetServices/GetOperations) rather than a trace query without a service.

Example fix

// before
reader.FindTraces(ctx, &tracestore.TraceQueryParams{StartTimeMin: t0, StartTimeMax: t1})
// after
reader.FindTraces(ctx, &tracestore.TraceQueryParams{ServiceName: "payments", StartTimeMin: t0, StartTimeMax: t1})

if query == nil || query.ServiceName == "" {
    return errors.New("service name is required for trace search")
}

ids, err := reader.FindTraceIDs(ctx, q)
if errors.Is(err, spanstore.ErrServiceNameNotSet) {
    return http.StatusBadRequest // or surface 'service name required' to the client
}

When it happens

Trigger: Calling SpanReader.FindTraceIDs or FindTraces with &tracestore.TraceQueryParams{...} where p.ServiceName == "" — typically when the caller builds a query from a request that omitted the service field.

Common situations: An API/gRPC client sends a search request without serviceName; a UI widget submits an empty service filter; custom tooling calling the storage layer directly without validating the query first.

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

• start Time Minimum is above Maximum
• duration Minimum is above Maximum
• malformed request object
• cannot query for duration and tags simultaneously
• start and End Time must be set

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