Factory storage domain '${domain.name}' is already registere

Error message

Factory storage domain '${domain.name}' is already registered

What it means

registerDomain() rejects adding a second domain whose name matches one already present in the storage's #domains map. Each factory storage domain name must be unique per storage instance, so duplicate registration is treated as a programming error and thrown immediately (before the duplicate would silently shadow the original).

Source

Thrown at packages/core/src/storage/factory-storage.ts:292

   * Agent-state store (threads, messages, memory, OM) for this database,
   * sharing this backend's connection. Callers pass the result to the Mastra
   * instance and all agent-related wiring. Lazily constructed; returns the
   * same instance on repeat calls.
   */
  abstract getMastraStorage(): MastraCompositeStore;

  /** Open/validate the backend, then initialize registered domains fail-soft. */
  async init(): Promise<void> {
    await this.#ensureStorageReady();
    await Promise.all([...this.#domains.keys()].map(name => this.#initDomain(name).catch(() => undefined)));
  }

  /** Backend-specific connection initialization. */
  protected abstract initStorage(): Promise<void>;

  registerDomain<T extends FactoryStorageDomain>(domain: T): T {
    if (this.#domains.has(domain.name)) {
      throw new Error(`Factory storage domain '${domain.name}' is already registered`);
    }
    domain.__bindFactoryStorage(this);
    this.#domains.set(domain.name, domain);
    return domain;
  }

  getDomain<T extends FactoryStorageDomain = FactoryStorageDomain>(name: string): T {
    const domain = this.#domains.get(name);
    if (!domain) {
      throw new Error(`Factory storage domain '${name}' is not registered`);
    }
    return domain as T;
  }

  hasDomain(name: string): boolean {
    return this.#domains.has(name);
  }

View on GitHub (pinned to 75dd419e61)

Solutions

Guard registration: check `storage.hasDomain(name)` before calling registerDomain, or reuse the existing domain via `storage.getDomain(name)`.
Ensure storage init runs only once (memoize/flag the init path, e.g. `if (inited) return`).
Give custom domains distinct `name` values.
If a backend re-registers domains in initStorage(), check hasDomain() first and skip.

Example fix

// before
await storage.init();
await storage.init(); // throws: already registered

// after
if (!storage.hasDomain('memorySettings')) {
  storage.registerDomain(new InMemoryMemorySettingsStorage());
}

Defensive patterns

Strategy: validation

Validate before calling

if (!storage.hasDomain(domain.name)) {
  storage.registerDomain(domain);
}

Try / catch

try {
  storage.registerDomain(domain);
} catch (e) {
  if (!e.message.includes('is already registered')) throw e;
  // reuse existing registration
  return storage.getDomain(domain.name);
}

Prevention

Make storage initialization idempotent (init-once flag or memoized promise).
Check hasDomain() before registerDomain in custom backends.
Ensure each custom domain has a unique name constant.
Avoid calling init() from multiple bootstrap paths (hot reload, workers).

When it happens

Trigger: Calling `storage.registerDomain(domain)` twice for domains with the same `name`, or calling registerDomain for a domain after re-running initStorage() (e.g. calling `init()` twice on the storage instance).

Common situations: Calling storage.init() more than once (hot reload, multiple bootstrap paths); two custom domains accidentally given the same name; subclass re-registering a parent's domain during re-initialization.

Related errors

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