Factory storage domain

Error message

Factory storage domain '${this.name}' has not been registered

What it means

A FactoryStorageDomain's underlying storage backend is only wired up when the owning storage class registers the domain (via registerDomain/__bindFactoryStorage). The protected `storage` getter throws when a domain is used before that binding happened, i.e. the domain object exists but no storage was ever attached to it.

Solutions

Register the domain with its owning storage instance before using it: `storage.registerDomain(domain)`.
Ensure the storage class's `initStorage()` implementation registers all domains (intakeStorage, memorySettingsStorage, etc.).
Call the storage's `init()`/initialization method before touching any domain methods.
In tests, use the storage factory/helper that wires domains instead of constructing domain objects directly.

Example fix

// before
const domains = new InMemoryMemorySettingsStorage();
domains.getSettings(); // throws: domain not registered

// after
const storage = new MastraStorage({ name: 'my-app' });
const domains = storage.registerDomain(new InMemoryMemorySettingsStorage());
await storage.init();
domains.getSettings(); // works

Defensive patterns

Strategy: validation

Validate before calling

function isDomainReady(domain) {
  return typeof domain.hasBeenInitialized === 'function'
    ? domain.hasBeenInitialized()
    : true;
}
// call after storage.init() and before using the domain

Type guard

function isBoundDomain(d) {
  return d != null && typeof d === 'object' && 'storage' in d && (d.__factoryStorage ?? null) !== undefined;
}

Try / catch

try {
  await domain.doWork();
} catch (e) {
  if (e.message.includes("has not been registered")) {
    await storage.init();
    return domain.doWork();
  }
  throw e;
}

Prevention

Always obtain domains from the storage instance (storage.registerDomain / typed accessors), never construct them standalone.
Call storage.init() once during app bootstrap before any storage access.
In tests, build domains through the same factory path production code uses.
Add an integration test that exercises each domain after a fresh storage init.

When it happens

Trigger: Instantiating a domain class (or subclass) and calling any method that reads `this.storage` without first registering it with a storage instance via `registerDomain()` / running the owning storage's `init()`.

Common situations: Constructing a domain directly with `new` in tests or custom code instead of getting it from the storage class; custom storage backends whose initStorage() forgets to register a domain; accessing a domain at module load time before storage init.

Related errors

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

Appendix: source

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

  protected constructor(name: string) {
    if (!name.trim()) {
      throw new Error('Factory storage domain name must not be empty');
    }
    super({ component: 'STORAGE', name });
    this.name = name;
  }

  /** @internal Bound by {@link FactoryStorage.registerDomain}. */
  __bindFactoryStorage(storage: FactoryStorage): void {
    if (this.#storage && this.#storage !== storage) {
      throw new Error(`Factory storage domain '${this.name}' is already bound to another storage instance`);
    }
    this.#storage = storage;
  }

  protected get storage(): FactoryStorage {
    if (!this.#storage) {
      throw new Error(`Factory storage domain '${this.name}' has not been registered`);
    }
    return this.#storage;
  }

  /**
   * Initialize this domain (via its owning storage) if it hasn't been yet.
   * Lets consumers holding a domain handle run the same fail-soft readiness
   * check as {@link FactoryStorage.ensureDomainReady} without also needing a
   * reference to the storage backend.
   */
  ensureReady(): Promise<void> {
    return this.storage.ensureDomainReady(this.name);
  }

  protected get ops(): FactoryStorageOps {
    return this.storage.ops;
  }

View on GitHub (pinned to 75dd419e61)