mastra-ai/mastra · error · MastraError

AGENT_NETWORK_MEMORY_REQUIRED

AGENT_NETWORK_MEMORY_REQUIRED

Error message

Memory is required for the agent network to function properly. Please configure memory for the agent.

What it means

Before starting an agent network, networkLoop validates that the routing agent can resolve a Memory instance via agent.getMemory(). Networks require memory to track threads, resources and inter-agent context, so a missing memory is a 400-class USER configuration error.

Source

Thrown at packages/core/src/loop/network/index.ts:2170

  /**
   * Structured output configuration for the network's final result.
   * When provided, generates a structured response matching the schema.
   */
  structuredOutput?: OUTPUT extends {} ? StructuredOutputOptions<OUTPUT> : never;

  resumeData?: any;
  autoResumeSuspendedTools?: boolean;
  mastra?: Mastra;
  onStepFinish?: NetworkOptions<OUTPUT>['onStepFinish'];
  onError?: NetworkOptions<OUTPUT>['onError'];
  onAbort?: NetworkOptions<OUTPUT>['onAbort'];
  abortSignal?: NetworkOptions<OUTPUT>['abortSignal'];
}): Promise<MastraAgentNetworkStream<OUTPUT>> {
  // Validate that memory is available before starting the network
  const memoryToUse = await routingAgent.getMemory({ requestContext });

  if (!memoryToUse) {
    throw new MastraError({
      id: 'AGENT_NETWORK_MEMORY_REQUIRED',
      domain: ErrorDomain.AGENT_NETWORK,
      category: ErrorCategory.USER,
      text: 'Memory is required for the agent network to function properly. Please configure memory for the agent.',
      details: {
        status: 400,
      },
    });
  }

  assertNetworkSupportsMemory(memoryToUse, routingAgentOptions?.memory?.options);

  const task = getLastMessage(messages);

  let resumeDataFromTask: any | undefined;
  let runIdFromTask: string | undefined;
  if (autoResumeSuspendedTools && threadId) {
    let lastAssistantMessage: MastraDBMessage | undefined;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Attach a Memory instance to the routing agent: new Agent({ ..., memory: new Memory({ storage }) }).
2. Ensure the storage backend passed to Memory is defined (configure LibSQL/Postgres/InMemory storage).
3. If getMemory is overridden, make sure it resolves to a Memory instance, not undefined.
4. Verify with agent.getMemory({ requestContext }) before calling network() that a memory resolves.

Example fix

// before
const agent = new Agent({ name: 'router', instructions: '...', model: 'openai/gpt-4o' });
await agent.network('do the task');
// after
const agent = new Agent({ name: 'router', instructions: '...', model: 'openai/gpt-4o', memory: new Memory({ storage: new LibSQLStore({ url: 'file:./mastra.db' }) }) });
await agent.network('do the task');

const mem = await routingAgent.getMemory({ requestContext });
if (!mem) throw new Error('Routing agent must have memory configured before agent.network()');
await routingAgent.network(input);

function hasMemory(a: { getMemory: (o: unknown) => Promise<unknown> }): a is Required<{ getMemory: (o: unknown) => Promise<object> }> {
  return typeof a.getMemory === 'function';
}
// usage: (await agent.getMemory({})) ? proceed : configure memory

try {
  await agent.network(input);
} catch (e) {
  if (e instanceof MastraError && e.id === 'AGENT_NETWORK_MEMORY_REQUIRED') {
    agent = new Agent({ ...agentConfig, memory: new Memory({ storage }) });
    return agent.network(input);
  }
  throw e;
}

When it happens

Trigger: Calling agent.network() (or the streaming entry that calls this validation) with an agent constructed without a memory option, or with a memory factory/config that resolves to undefined at runtime (e.g. getMemory override returning nothing).

Common situations: Creating a minimal Agent({ name, model }) for network testing without memory; a custom getMemory() override that returns undefined when storage is not configured; refactoring memory out of an agent that is still used as a network routing agent.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• AGENT_NETWORK_OBSERVATIONAL_MEMORY_UNSUPPORTED
• Semantic recall requires a vector store to be configured. h
• Memory requires a storage provider to function. Add a storag
• Credential storage is not available
• Factory source control storage is unavailable

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