jaegertracing/jaeger · error

root span top-hit missing _source

Error message

root span top-hit missing _source

What it means

This error is raised by parseRootSpan in summary.go when the top-hit document of the root-span aggregation (named "root_hit") has an empty _source field. Trace summaries need the root span's service name and operation name, which are read from the hit's _source; without it, parsing cannot proceed and parseTraceSummaries surfaces the error.

Source

Thrown at internal/storage/v2/elasticsearch/tracestore/core/summary.go:261

// parseRootSpan returns the service and operation of the trace's root span, taken
// from the earliest span that has no parentSpanID (see buildTraceSummariesAggregation).
//
// Empty values with a nil error are returned when the trace has no parentless span
// (a valid outcome); a malformed top-hit _source is surfaced as an error rather
// than dropped.
func parseRootSpan(bucket esclient.AggregationBucket) (serviceName, operationName string, err error) {
	rootSpan, ok := bucket.Filter("root_span")
	if !ok {
		return "", "", nil
	}
	topHits, ok := rootSpan.TopHits("root_hit")
	if !ok || len(topHits.Hits) == 0 {
		return "", "", nil
	}
	source := topHits.Hits[0].Source
	if len(source) == 0 {
		return "", "", errors.New("root span top-hit missing _source")
	}
	var parsed rootSpanSource
	if err := json.Unmarshal(source, &parsed); err != nil {
		return "", "", fmt.Errorf("failed to decode root span source: %w", err)
	}
	return parsed.Process.ServiceName, parsed.OperationName, nil
}

View on GitHub (pinned to 806f444784)

Solutions

1. Verify the span documents in Elasticsearch actually contain full _source (check a raw document with GET <index>/_doc/<id>).
2. Ensure the search request does not disable or filter out _source for the root_hit top-hits aggregation.
3. Re-index or rewrite affected indices if documents were written without source by an older writer.
4. Check index templates/mappings for source filtering that empties _source.

// Pre-flight: confirm a sample root-span document has non-empty _source
var doc map[string]any
err := esAPI.Get(ctx, index, id, &doc)
if err != nil || len(doc) == 0 { /* index lacks source data */ }

summary, err := reader.GetTraceSummary(ctx, traceID)
if err != nil && strings.Contains(err.Error(), "root span top-hit missing _source") {
    // fall back to full trace fetch or reindex the affected index
}

When it happens

Trigger: Calling the trace summary read path where the ES top-hits aggregation returns a hit whose Source bytes are empty — e.g. stored_span documents written without full _source, mapping-only hits, or fetch_source disabled in the search request.

Common situations: Indices written by an older/different writer that did not store full documents; custom index templates with source filtering; querying a summary endpoint against indices lacking the expected root-span documents.

Related errors

• could not find aggregation of traceIDs
• nil search response
• could not find aggregation of
• file must begin with '['
• max spans count reached

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