mastra-ai/mastra · error

chat module not loaded yet — call getChatModule() first

Error message

chat module not loaded yet — call getChatModule() first

What it means

chatModule() is the synchronous accessor for the lazily-loaded `chat` module. The module is only populated after awaiting getChatModule(). This guard Error prevents using the sync accessor before the async load completed. It is an initialization-order contract enforced at runtime.

Source

Thrown at packages/core/src/channels/chat-lazy.ts:46

    return cached;
  }
  if (!loading) {
    loading = (async () => {
      const chatModule = await import(/* @vite-ignore */ /* webpackIgnore: true */ 'chat');
      cached = chatModule;
      return chatModule;
    })();
  }
  return loading;
}

/**
 * Synchronous accessor for the `chat` module.
 * Only safe to call after `getChatModule()` has been awaited (e.g. after `AgentChannels.initialize()`).
 */
export function chatModule(): ChatModule {
  if (!cached) {
    throw new Error('chat module not loaded yet — call getChatModule() first');
  }
  return cached;
}

export type { Chat };

View on GitHub (pinned to 75dd419e61)

Solutions

1. Await getChatModule() once during startup (e.g. in AgentChannels.initialize()) before any chatModule() call.
2. Replace top-level chatModule() usage with the async getChatModule() flow.
3. Move chat-dependent initialization into an async init function that first awaits getChatModule().

Example fix

// before
import { chatModule } from './chat-lazy';
const chat = chatModule(); // throws at import time
// after
import { getChatModule, chatModule } from './chat-lazy';
await getChatModule();
const chat = chatModule();

import { getChatModule } from './chat-lazy';
export async function ensureChatReady() { await getChatModule(); } // call once at startup before any sync accessor use

null

try { const m = chatModule(); } catch { await getChatModule(); const m = chatModule(); }

When it happens

Trigger: Calling chatModule() before any code has awaited getChatModule() — e.g. at module top level, or in code paths that run before AgentChannels.initialize() (or equivalent) has resolved the dynamic import.

Common situations: Importing a helper that synchronously calls chatModule() during app bootstrap; calling chat functions before initializing AgentChannels; top-level module code that touches chat APIs without awaiting the loader.

Related errors

• AgentControllerChannels is not bound to an AgentController.
• MastraAuthBetterAuth is not initialized — init() must run fi
• Shared browser not launched. Call createSharedSession() firs
• MastraFactory: integrations [${channelRegistrations.map(({ i
• MastraFactory.finalize() called before prepare()

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