Channels require storage to be configured on the Mastra inst

Error message

Channels require storage to be configured on the Mastra instance. Configure a storage provider like LibSQLStore.

What it means

AgentChannels.initialize needs a persistent state adapter to store channel subscriptions. Unless a custom state adapter was supplied, it requires the Mastra instance to have storage configured with a memory store; otherwise it throws this configuration error at startup.

Source

Thrown at packages/core/src/channels/agent-channels.ts:404

  /**
   * Initialize the Chat SDK, register handlers, and start gateway listeners.
   * Called by Mastra.addAgent after the server is ready.
   */
  async initialize(mastra: Mastra): Promise<void> {
    if (this.chat) return;
    if (this.initPromise) {
      return this.initPromise;
    }

    this.initPromise = (async () => {
      // Resolve state adapter: custom > Mastra storage > in-memory fallback
      if (this.customState) {
        this.stateAdapter = this.customState;
      } else {
        const storage = mastra.getStorage();
        const memoryStore = storage ? await storage.getStore('memory') : undefined;
        if (!memoryStore) {
          throw new Error(
            'Channels require storage to be configured on the Mastra instance. Configure a storage provider like LibSQLStore.',
          );
        }
        this.stateAdapter = new MastraStateAdapter(memoryStore, () => this.getOwnerId());
        this.log('info', 'Using MastraStateAdapter (subscriptions persist across restarts)');
      }

      const { Chat, Message: ChatMessage, ThreadImpl } = await getChatModule();
      const chat = new Chat({
        adapters: this.adapters,
        state: this.stateAdapter,
        userName: this.userName,
        // Dispatch every incoming message immediately. Concurrency and queueing
        // for the same thread are handled by the agent signals layer
        // (ifActive/ifIdle behaviors), so chat-sdk's own lock-based queue would
        // be redundant — and in serverless runtimes a stale lock from a frozen
        // Lambda can cause subsequent messages to be queued forever.
        concurrency: { strategy: 'concurrent' },

View on GitHub (pinned to 75dd419e61)

Solutions

Configure storage on the Mastra instance, e.g. `new Mastra({ storage: new LibSQLStore({ url: 'file:./mastra.db' }) })`
Pass a custom state adapter via the channel's customState option if you do not want Mastra storage
Verify your storage provider implements getStore('memory') — some minimal providers may not

Example fix

// before
new Mastra({ agents: { myAgent } }); // no storage
// after
import { LibSQLStore } from '@mastra/libsql';
new Mastra({ agents: { myAgent }, storage: new LibSQLStore({ url: 'file:./mastra.db' }) });

Defensive patterns

Strategy: validation

Validate before calling

const storage = mastra.getStorage();
if (!storage || !(await storage.getStore('memory'))) {
  throw new Error('Configure a storage provider with a memory store before initializing channels');
}

Type guard

function hasMemoryStore(s: unknown): s is StorageType {
  return !!s && typeof (s as StorageType).getStore === 'function';
}

Try / catch

try {
  await channels.initialize(mastra);
} catch (err) {
  if (err instanceof Error && err.message.includes('Channels require storage')) {
    console.error('Add storage: new Mastra({ storage: new LibSQLStore({...}) })');
  } else throw err;
}

Prevention

Always configure storage in production Mastra bootstraps
Add a startup assertion that storage + memory store exist before channel init
Keep customState alternative in mind for storage-less setups

When it happens

Trigger: Constructing an AgentChannels (or registering a channel) on a Mastra instance created without `storage: new LibSQLStore(...)` (or another storage provider exposing a memory store), then calling initialize.

Common situations: Local dev or examples where storage was omitted for simplicity, deploying a channels-enabled agent after copying a minimal Mastra bootstrap, or using a storage provider that does not implement the memory store.

Related errors

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