{"record":{"id":"97f122cf529e1235","repo":"mastra-ai/mastra","slug":"observability-storage-list-branches-not-implemente","errorCode":"OBSERVABILITY_STORAGE_LIST_BRANCHES_NOT_IMPLEMENTED","errorMessage":"This storage provider does not support listing trace branches","messagePattern":"This storage provider does not support listing trace branches","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/domains/observability/base.ts","lineNumber":352,"sourceCode":"   * serves the same response shape whether or not it has a dedicated implementation.\n   * Backends that can push the projection into the query should override this --\n   * that is what actually keeps the blob columns off the read path -- but the\n   * fallback stays correct, just not cheaper than `listTraces`.\n   */\n  async listTracesLight(args: ListTracesArgs): Promise<ListTracesLightResponse> {\n    const { spans, ...rest } = await this.listTraces(args);\n    return { ...rest, spans: spans.map(toLightSpanRecord) };\n  }\n\n  /**\n   * Lists trace branches across all traces. Unlike {@link listTraces} (which\n   * returns one row per root-rooted trace), each row here is a single branch\n   * anchor span, including ones nested under a different root entity -- useful\n   * for \"show me every run of agent X\" regardless of caller. Pairs with\n   * {@link getBranch} to expand a single branch into its subtree.\n   */\n  async listBranches(_args: ListBranchesArgs): Promise<ListBranchesResponse> {\n    throw new MastraError({\n      id: 'OBSERVABILITY_STORAGE_LIST_BRANCHES_NOT_IMPLEMENTED',\n      domain: ErrorDomain.MASTRA_OBSERVABILITY,\n      category: ErrorCategory.SYSTEM,\n      text: 'This storage provider does not support listing trace branches',\n    });\n  }\n\n  /**\n   * Creates multiple Spans in a single batch.\n   */\n  async batchCreateSpans(_args: BatchCreateSpansArgs): Promise<void> {\n    throw new MastraError({\n      id: 'OBSERVABILITY_STORAGE_BATCH_CREATE_SPAN_NOT_IMPLEMENTED',\n      domain: ErrorDomain.MASTRA_OBSERVABILITY,\n      category: ErrorCategory.SYSTEM,\n      text: 'This storage provider does not support batch creating spans',\n    });\n  }","sourceCodeStart":334,"sourceCodeEnd":370,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/observability/base.ts#L334-L370","documentation":"listBranches() returns one row per branch anchor span (each runnable branch of a trace, not just one per root), designed to pair with getBranch() to expand a branch into its subtree. The base class default throws, meaning the adapter does not support branch-level trace listing.","triggerScenarios":"Calling listBranches({ ... }) — e.g. 'show me every run of agent X' style queries — on an adapter that never overrode it; UI routes enumerating branches before calling getBranch().","commonSituations":"Adapters implementing flat trace listing (listTraces) but not the newer branch model; custom storage written before branch-aware observability; minimal backends without nested-run support.","solutions":["Use a storage adapter that implements listBranches (upgrade the storage package if needed).","Implement listBranches() in your adapter (select anchor spans and derive branch metadata).","Fall back to listTraces()/getTrace() and enumerate branches by walking parent-child links client-side.","Capability-check before calling and degrade to root-level trace listing."],"exampleFix":"// before\nconst branches = await observability.listBranches(args);\n\n// after (fallback)\nconst { traces } = await observability.listTraces(args);\nconst branches = traces; // root-level listing as coarse approximation","handlingStrategy":"fallback","validationCode":"const supportsListBranches = obs.listBranches !== ObservabilityStorage.prototype.listBranches;","typeGuard":"function supportsListBranches(o: { listBranches: unknown }): boolean {\n  return o.listBranches !== (ObservabilityStorage.prototype as any).listBranches;\n}","tryCatchPattern":"try {\n  return await obs.listBranches(args);\n} catch (e) {\n  if ((e as MastraError).id === 'OBSERVABILITY_STORAGE_LIST_BRANCHES_NOT_IMPLEMENTED') {\n    const { traces } = await obs.listTraces(args).catch(() => ({ traces: [] }));\n    return traces;\n  }\n  throw e;\n}","preventionTips":["Use adapters that support the branch model when you need per-branch run listings.","Fall back to root-level listTraces when branch enumeration is unavailable.","Add branch reads to your adapter's test matrix."],"tags":["storage","observability","tracing","branches","unsupported-operation"],"backgroundTag":"storage-provider-not-implemented","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}