jaegertracing/jaeger · warning

trace not found

Error message

trace not found

What it means

The get_trace_topology MCP tool fetches a trace by ID via the query service and builds a topology (parent/child span tree). It throws "trace not found" when the trace lookup completed without error but no spans were returned, so traceFound stays false and there is no topology to report. It signals that the requested trace ID does not exist in the queried storage (or is not visible to it), as opposed to a malformed ID (which produces the "invalid trace_id" error from buildQuery).

Source

Thrown at cmd/jaeger/internal/extension/jaegerquery/internal/mcptools/internal/handlers/get_trace_topology.go:94

	for trace, err := range aggregatedIter {
		if err != nil {
			return nil, types.GetTraceTopologyOutput{}, fmt.Errorf("failed to get trace: %w", err)
		}

		traceFound = true

		// Iterate through all spans in the trace and collect them
		for pos, span := range jptrace.SpanIter(trace) {
			spans = append(spans, extractRawSpan(pos, span))
			if h.maxSpanDetailsPerRequest > 0 && len(spans) >= h.maxSpanDetailsPerRequest {
				break
			}
		}
	}

	if !traceFound {
		return nil, types.GetTraceTopologyOutput{}, errors.New("trace not found")
	}

	// Build the flat topology list from the collected spans
	output := types.GetTraceTopologyOutput{
		TraceID: input.TraceID,
		Spans:   h.buildFlatTopology(spans, input.Depth),
	}

	return nil, output, nil
}

// buildQuery converts GetTraceTopologyInput to querysvc.GetTraceParams.
func (*getTraceTopologyHandler) buildQuery(input types.GetTraceTopologyInput) (querysvc.GetTraceParams, error) {
	// Validate input
	if input.TraceID == "" {
		return querysvc.GetTraceParams{}, errors.New("trace_id is required")
	}

View on GitHub (pinned to 806f444784)

Solutions

1. Re-verify the trace ID against the source (UI URL, OTel exporter logs, or the system that produced it); a single wrong hex character yields this error.
2. Confirm the jaegerquery extension points at the same storage the trace was ingested into (check storage config / SPAN_STORAGE env).
3. Check whether the trace falls within the retention period of the backend; if it is older, it is gone.
4. Search for traces by service/time range to confirm the backend has data at all, then retry with the correct ID.

Example fix

// before: querying with an ID copied from another env
output, err := h.handle(ctx, types.GetTraceTopologyInput{TraceID: "4bf92f3577b34da6a3ce929d0e0e4736"})
// after: verify the ID exists in THIS backend first
found, err := h.queryService.FindTraceByID(ctx, traceID)
if err != nil || found == nil {
    // pick the right ID from a search, then call the topology tool
}

if len(strings.TrimSpace(traceID)) != 32 { return fmt.Errorf("trace ID must be 32 hex chars, got %q", traceID) }

func isLikelyTraceID(s string) bool {
	_, err := hex.DecodeString(s)
	return err == nil && (len(s) == 16 || len(s) == 32)
}

output, err := handler.Handle(ctx, input)
if err != nil {
    if err.Error() == "trace not found" {
        log.Warnf("trace %s not found in this backend; verify ID/storage/retention", input.TraceID)
        return ErrTraceNotFound // map to 404-style handling
    }
    return err
}

When it happens

Trigger: Calling the MCP get_trace_topology tool with a TraceID that (a) never existed, (b) was written to a different storage backend than the query extension reads from, (c) has aged out of the retention window, or (d) exists but the reader returns zero spans for it.

Common situations: Copy-pasting a trace ID from another Jaeger instance or environment; querying a span that predates data retention; typos in the trace ID that still parse as valid (e.g. wrong hex digits); storage index/replication lag where the ID exists but is not yet searchable.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• trace not found
• failed to get trace: %w
• trace not found
• trace_id is required
• start_time must be before end_time

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