{"record":{"id":"7017fc38d0c64355","repo":"jaegertracing/jaeger","slug":"trace-not-found-7017fc","errorCode":null,"errorMessage":"trace not found","messagePattern":"trace not found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"cmd/jaeger/internal/extension/jaegerquery/internal/mcptools/internal/handlers/get_trace_topology.go","lineNumber":94,"sourceCode":"\n\tfor trace, err := range aggregatedIter {\n\t\tif err != nil {\n\t\t\treturn nil, types.GetTraceTopologyOutput{}, fmt.Errorf(\"failed to get trace: %w\", err)\n\t\t}\n\n\t\ttraceFound = true\n\n\t\t// Iterate through all spans in the trace and collect them\n\t\tfor pos, span := range jptrace.SpanIter(trace) {\n\t\t\tspans = append(spans, extractRawSpan(pos, span))\n\t\t\tif h.maxSpanDetailsPerRequest > 0 && len(spans) >= h.maxSpanDetailsPerRequest {\n\t\t\t\tbreak\n\t\t\t}\n\t\t}\n\t}\n\n\tif !traceFound {\n\t\treturn nil, types.GetTraceTopologyOutput{}, errors.New(\"trace not found\")\n\t}\n\n\t// Build the flat topology list from the collected spans\n\toutput := types.GetTraceTopologyOutput{\n\t\tTraceID: input.TraceID,\n\t\tSpans:   h.buildFlatTopology(spans, input.Depth),\n\t}\n\n\treturn nil, output, nil\n}\n\n// buildQuery converts GetTraceTopologyInput to querysvc.GetTraceParams.\nfunc (*getTraceTopologyHandler) buildQuery(input types.GetTraceTopologyInput) (querysvc.GetTraceParams, error) {\n\t// Validate input\n\tif input.TraceID == \"\" {\n\t\treturn querysvc.GetTraceParams{}, errors.New(\"trace_id is required\")\n\t}\n","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/jaegertracing/jaeger/blob/806f4447841ecdb60519f408b004a599d515f437/cmd/jaeger/internal/extension/jaegerquery/internal/mcptools/internal/handlers/get_trace_topology.go#L76-L112","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Confirm the jaegerquery extension points at the same storage the trace was ingested into (check storage config / SPAN_STORAGE env).","Check whether the trace falls within the retention period of the backend; if it is older, it is gone.","Search for traces by service/time range to confirm the backend has data at all, then retry with the correct ID."],"exampleFix":"// before: querying with an ID copied from another env\noutput, err := h.handle(ctx, types.GetTraceTopologyInput{TraceID: \"4bf92f3577b34da6a3ce929d0e0e4736\"})\n// after: verify the ID exists in THIS backend first\nfound, err := h.queryService.FindTraceByID(ctx, traceID)\nif err != nil || found == nil {\n    // pick the right ID from a search, then call the topology tool\n}","handlingStrategy":"validation","validationCode":"if len(strings.TrimSpace(traceID)) != 32 { return fmt.Errorf(\"trace ID must be 32 hex chars, got %q\", traceID) }","typeGuard":"func isLikelyTraceID(s string) bool {\n\t_, err := hex.DecodeString(s)\n\treturn err == nil && (len(s) == 16 || len(s) == 32)\n}","tryCatchPattern":"output, err := handler.Handle(ctx, input)\nif err != nil {\n    if err.Error() == \"trace not found\" {\n        log.Warnf(\"trace %s not found in this backend; verify ID/storage/retention\", input.TraceID)\n        return ErrTraceNotFound // map to 404-style handling\n    }\n    return err\n}","preventionTips":["Source trace IDs from the same Jaeger instance you query; embed environment in the ID's origin metadata.","Alert on retention boundaries — traces near the retention limit will silently disappear.","Sanity-check the backend has any data (search by service) before diagnosing individual IDs."],"tags":["mcp","trace-lookup","not-found"],"backgroundTag":"resource-not-found","analyzedSha":"806f4447841ecdb60519f408b004a599d515f437","analyzedAt":"2026-09-01T02:39:22.140Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}