{"record":{"id":"4a280682dff9a80e","repo":"jaegertracing/jaeger","slug":"trace-not-found-4a2806","errorCode":null,"errorMessage":"trace not found","messagePattern":"trace not found","errorType":"exception","errorClass":null,"httpStatus":404,"severity":"warning","filePath":"internal/storage/v1/api/spanstore/interface.go","lineNumber":17,"sourceCode":"// Copyright (c) 2019 The Jaeger Authors.\n// Copyright (c) 2017 Uber Technologies, Inc.\n// SPDX-License-Identifier: Apache-2.0\n\npackage spanstore\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"time\"\n\n\t\"github.com/jaegertracing/jaeger-idl/model/v1\"\n\t\"github.com/jaegertracing/jaeger/internal/storage/v2/api/tracestore\"\n)\n\n// ErrTraceNotFound is returned by Reader's GetTrace if no data is found for given trace ID.\nvar ErrTraceNotFound = errors.New(\"trace not found\")\n\n// Writer writes spans to storage.\ntype Writer interface {\n\tWriteSpan(ctx context.Context, span *model.Span) error\n}\n\n// Reader finds and loads traces and other data from storage.\ntype Reader interface {\n\t// GetTrace retrieves the trace with a given id.\n\t//\n\t// If no spans are stored for this trace, it returns ErrTraceNotFound.\n\tGetTrace(ctx context.Context, query GetTraceParameters) (*model.Trace, error)\n\n\t// GetServices returns all service names known to the backend from spans\n\t// within its retention period.\n\tGetServices(ctx context.Context) ([]string, error)\n\n\t// GetOperations returns all operation names for a given service","sourceCodeStart":1,"sourceCodeEnd":35,"githubUrl":"https://github.com/jaegertracing/jaeger/blob/806f4447841ecdb60519f408b004a599d515f437/internal/storage/v1/api/spanstore/interface.go#L1-L35","documentation":"ErrTraceNotFound is the sentinel error declared in the v1 spanstore API that Reader.GetTrace implementations return when no spans exist for the requested trace ID. Callers are expected to check it with errors.Is so that 'trace missing' is treated as a normal, empty result (e.g. HTTP 404) rather than an internal failure. It is also propagated by helpers like unwrapNotFoundErr and gateway tryHandleError adapters.","triggerScenarios":"Calling GetTrace with a trace ID that was never written, has been TTL-aged out of storage, or was written to a different backend/namespace; also returned by ArchiveTrace and forwarded by tryHandleError paths when the underlying store reports no data.","commonSituations":"UI/user follows a link to an old trace that exceeded retention; wrong storage backend configured (e.g. pointing at an ES index without that trace); trace ID typo or truncated ID from a log line; tests that assert before the writer's async flush is visible to the reader.","solutions":["Check errors.Is(err, spanstore.ErrTraceNotFound) and treat it as 404 / empty result, not a server error.","Verify the trace ID is correct (full 128-bit ID, no truncation or copy/paste artifacts).","Confirm the query is hitting the same storage backend and tenant/namespace the trace was written to.","If traces expire sooner than expected, increase the backend retention/TTL settings.","If writing then immediately reading, ensure the write completed and became visible (account for buffering in the writer pipeline)."],"exampleFix":"// before\ntrace, err := reader.GetTrace(ctx, spanstore.GetTraceParameters{TraceID: id})\nif err != nil {\n\treturn err\n}\n// after\ntrace, err := reader.GetTrace(ctx, spanstore.GetTraceParameters{TraceID: id})\nif errors.Is(err, spanstore.ErrTraceNotFound) {\n\treturn nil, errNotFound // map to HTTP 404\n}\nif err != nil {\n\treturn nil, err\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"func isTraceNotFound(err error) bool {\n\treturn errors.Is(err, spanstore.ErrTraceNotFound)\n}","tryCatchPattern":"trace, err := reader.GetTrace(ctx, spanstore.GetTraceParameters{TraceID: id})\nswitch {\ncase errors.Is(err, spanstore.ErrTraceNotFound):\n\treturn http.StatusNotFound // expected empty result\ncase err != nil:\n\treturn http.StatusInternalServerError\n}\nreturn trace","preventionTips":["Always classify with errors.Is(err, spanstore.ErrTraceNotFound) instead of string comparison.","Validate trace IDs at ingestion/log-correlation time to avoid typo-driven lookups.","Keep retention/TTL settings aligned with how long consumers may follow trace links.","Ensure writers and readers point at the same backend, namespace, and index prefix."],"tags":["go","storage","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"}