{"record":{"id":"71700180fe2ff2b1","repo":"mastra-ai/mastra","slug":"tracing-instance-name-already-registered","errorCode":null,"errorMessage":"Tracing instance '${name}' already registered","messagePattern":"Tracing instance '(.+?)' already registered","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"observability/mastra/src/registry.ts","lineNumber":26,"sourceCode":"\n// ============================================================================\n// Observability Registry\n// ============================================================================\n\n/**\n * Registry for Observability instances.\n */\nexport class ObservabilityRegistry {\n  #instances = new Map<string, ObservabilityInstance>();\n  #defaultInstance?: ObservabilityInstance;\n  #configSelector?: ConfigSelector;\n\n  /**\n   * Register a tracing instance\n   */\n  register(name: string, instance: ObservabilityInstance, isDefault = false): void {\n    if (this.#instances.has(name)) {\n      throw new Error(`Tracing instance '${name}' already registered`);\n    }\n\n    this.#instances.set(name, instance);\n\n    // Set as default if explicitly marked or if it's the first instance\n    if (isDefault || !this.#defaultInstance) {\n      this.#defaultInstance = instance;\n    }\n  }\n\n  /**\n   * Get a tracing instance by name\n   */\n  get(name: string): ObservabilityInstance | undefined {\n    return this.#instances.get(name);\n  }\n\n  /**","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/observability/mastra/src/registry.ts#L8-L44","documentation":"MastraTraceRegistry.register stores observability instances by unique name and throws if a name is already taken. Duplicate registration is treated as a programming/config error rather than a silent overwrite, because it usually indicates the same tracing instance is being initialized twice. Register via Mastra constructor config (registerInstance) or directly — but only once per name per process.","triggerScenarios":"Calling registry.register(name, instance) (or registering the same named instance in the Mastra constructor) when an instance with that name already exists — e.g. hot module reload re-running initialization, a script constructing Mastra twice in one process, or two modules each registering 'default'.","commonSituations":"Dev servers with HMR re-executing setup code; test setup files run per-suite with shared global registry; monorepo code importing both @mastra/observability and app-level singletons that each register the same name; accidental duplicate key in tracing config.","solutions":["Register each tracing instance only once — move registration into app bootstrap, guarded by a module-level singleton.","Use a distinct name for each instance, or call the registry's get/fetch accessor to reuse the existing instance instead of re-registering.","If HMR causes it, dispose/unregister on module teardown (e.g. import.meta.hot.dispose) or cache the instance on globalThis.","In tests, create a fresh registry per test or clear registered instances in beforeEach."],"exampleFix":"// before: re-registers on HMR\nexport const mastra = new Mastra({ observability: { instances: { default: { provider: 'OTEL' } } } });\n// after: reuse existing instance on hot reload\nconst existing = (globalThis as any).__mastra;\nexport const mastra = existing ?? new Mastra({ observability: { instances: { default: { provider: 'OTEL' } } } });\n(globalThis as any).__mastra = mastra;","handlingStrategy":"try-catch","validationCode":"// check before registering\nif (registry.has?.(name) /* or track your own set */) {\n  console.warn(`Tracing instance '${name}' already registered; skipping`);\n} else {\n  registry.register(name, instance);\n}","typeGuard":"null","tryCatchPattern":"try {\n  registry.register(name, instance);\n} catch (err) {\n  if (String(err.message).includes('already registered')) {\n    instance = registry.get(name); // reuse existing\n  } else throw err;\n}","preventionTips":["Register observability instances once, in application bootstrap only.","Cache the Mastra instance on globalThis in dev to survive HMR.","In tests, build a fresh registry or clear it in beforeEach.","Use unique, descriptive instance names instead of reusing 'default'."],"tags":["configuration","registry","duplicate-key","tracing"],"backgroundTag":"duplicate-registration","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}