What causes "Tracing instance '${name}' already registered" in mastra-ai/mastra?

Register each tracing instance only once — move registration into app bootstrap, guarded by a module-level singleton.

Tracing instance '${name}' already registered

Error message

Tracing instance '${name}' already registered

What it means

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.

Source

Thrown at observability/mastra/src/registry.ts:26

// ============================================================================
// Observability Registry
// ============================================================================

/**
 * Registry for Observability instances.
 */
export class ObservabilityRegistry {
  #instances = new Map<string, ObservabilityInstance>();
  #defaultInstance?: ObservabilityInstance;
  #configSelector?: ConfigSelector;

  /**
   * Register a tracing instance
   */
  register(name: string, instance: ObservabilityInstance, isDefault = false): void {
    if (this.#instances.has(name)) {
      throw new Error(`Tracing instance '${name}' already registered`);
    }

    this.#instances.set(name, instance);

    // Set as default if explicitly marked or if it's the first instance
    if (isDefault || !this.#defaultInstance) {
      this.#defaultInstance = instance;
    }
  }

  /**
   * Get a tracing instance by name
   */
  get(name: string): ObservabilityInstance | undefined {
    return this.#instances.get(name);
  }

  /**

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before: re-registers on HMR
export const mastra = new Mastra({ observability: { instances: { default: { provider: 'OTEL' } } } });
// after: reuse existing instance on hot reload
const existing = (globalThis as any).__mastra;
export const mastra = existing ?? new Mastra({ observability: { instances: { default: { provider: 'OTEL' } } } });
(globalThis as any).__mastra = mastra;

Defensive patterns

Strategy: try-catch

Validate before calling

// check before registering
if (registry.has?.(name) /* or track your own set */) {
  console.warn(`Tracing instance '${name}' already registered; skipping`);
} else {
  registry.register(name, instance);
}

Type guard

null

Try / catch

try {
  registry.register(name, instance);
} catch (err) {
  if (String(err.message).includes('already registered')) {
    instance = registry.get(name); // reuse existing
  } else throw err;
}

Prevention

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'.

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/71700180fe2ff2b1. Report an issue: GitHub.