jaegertracing/jaeger · error

service name must be set

Error message

service name must be set

What it means

ErrServiceNameNotSet is returned by the badger spanstore's validateQuery when a FindTraces/FindTraceIDs query supplies tags or an operation name without a service name. In the badger backend, service name is a required component of the index keys, so such a query cannot be executed. Other backends (ES, Cassandra) declare equivalent errors with slightly different validation rules.

Source

Thrown at internal/storage/v1/badger/spanstore/reader.go:28

	"encoding/json"
	"errors"
	"fmt"
	"math"
	"slices"

	"github.com/dgraph-io/badger/v4"
	"golang.org/x/exp/maps"

	"github.com/jaegertracing/jaeger-idl/model/v1"
	"github.com/jaegertracing/jaeger/internal/storage/v1/api/spanstore"
	"github.com/jaegertracing/jaeger/internal/storage/v2/api/tracestore"
)

// Most of these errors are common with the ES and Cassandra backends. Each backend has slightly different validation rules.

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("min start time is above max")

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

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

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

	// ErrUnableToFindTraceIDAggregation occurs when an aggregation query for TraceIDs fail.
	ErrUnableToFindTraceIDAggregation = errors.New("could not find aggregation of traceIDs")

	// ErrNotSupported during development, don't support every option - yet
	ErrNotSupported = errors.New("this query parameter is not supported yet")

View on GitHub (pinned to 806f444784)

Solutions

1. Set query.ServiceName before adding OperationName or Tags to the search parameters.
2. If you only have tags, first discover candidate services via GetServices or by including the service name from span context.
3. Update API clients/UI to always send the service field for operation- or tag-scoped searches.

Example fix

// before
q := &spanstore.TraceQueryParameters{OperationName: "GET /api", Tags: tags}
ids, err := reader.FindTraceIDs(ctx, q)
// after
q := &spanstore.TraceQueryParameters{ServiceName: "frontend", OperationName: "GET /api", Tags: tags}
ids, err := reader.FindTraceIDs(ctx, q)

func validateBadgerQuery(q *spanstore.TraceQueryParameters) error {
	if q == nil {
		return errors.New("query is nil")
	}
	if q.ServiceName == "" && (q.OperationName != "" || len(q.Tags) > 0) {
		return errors.New("service name is required when filtering by operation or tags")
	}
	return nil
}

ids, err := reader.FindTraceIDs(ctx, q)
if errors.Is(err, spanstore.ErrServiceNameNotSet) {
	return nil, httpError(400, "service name is required for this search")
}
if err != nil { return nil, err }

When it happens

Trigger: Calling FindTraceIDs/FindTraces with TraceQueryParameters where ServiceName == "" while Tags is non-empty or OperationName != ""; e.g. a search form that only fills in an operation or tag filter.

Common situations: Query UI/API callers omitting the service dropdown; API clients building search requests programmatically and assuming tags alone are enough; older clients relying on backend-specific behavior.

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

• min start time is above max
• min duration is above max
• malformed request object
• start and end time must be set
• could not find aggregation of traceIDs

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