mastra-ai/mastra · error · HTTPException

Mastra instance is required for agent-backed responses

Error message

Mastra instance is required for agent-backed responses

What it means

Resolving an agent requires the Mastra instance to be available on the server. When resolveResponseAgent is called with mastra undefined, it throws this 500 because agent lookup (getAgentFromSystem) is impossible without it. This indicates a server wiring problem, not a client mistake.

Source

Thrown at packages/server/src/server/handlers/responses.ts:307

/**
 * Resolves the registered Mastra agent that owns the response request.
 */
async function resolveResponseAgent({
  mastra,
  agentId,
}: {
  mastra: Mastra | undefined;
  agentId?: string;
}): Promise<Agent<any, any, any, any>> {
  if (!agentId) {
    throw new HTTPException(400, {
      message: 'Responses requests require an agent_id',
    });
  }

  if (!mastra) {
    throw new HTTPException(500, { message: 'Mastra instance is required for agent-backed responses' });
  }

  return getAgentFromSystem({ mastra, agentId });
}

async function resolveAgentMemoryStore({
  agent,
  requestContext,
  errorMessage,
}: {
  agent: Agent<any, any, any, any>;
  requestContext: RequestContext;
  errorMessage: string;
}): Promise<MemoryStorage> {
  const agentMemoryStore = await getAgentMemoryStore({ agent, requestContext });
  if (!agentMemoryStore) {
    throw new HTTPException(400, { message: errorMessage });
  }

View on GitHub (pinned to 75dd419e61)

Solutions

Fix server bootstrap so the Mastra instance is constructed and passed to the responses handlers
Ensure agents are registered in the Mastra instance (agents map) before serving requests
Check for initialization errors earlier in server startup logs
If using a custom deployment, use the standard mastra dev/server wiring that injects mastra

Example fix

// before
createHandler({ mastra: undefined });
// after
import { mastra } from './mastra';
createHandler({ mastra });

Defensive patterns

Strategy: try-catch

Validate before calling

if (!mastra) throw new Error('Mastra instance missing from handler context');

Type guard

function hasMastra(ctx) { return ctx != null && typeof ctx.mastra === 'object'; }

Try / catch

try {
  await callResponsesApi(payload);
} catch (e) {
  if (e?.status === 500 && /Mastra instance is required/.test(e.message)) {
    // server misconfiguration: report to ops, do not retry
  }
  throw e;
}

Prevention

Use standard mastra server bootstrap so mastra is injected into handlers
Add a startup check that the Mastra instance is constructed and agents are registered
Cover handler wiring in an integration test

When it happens

Trigger: POST /api/responses reaching the handler while the Mastra instance failed to initialize or was not injected into the handler context (e.g., misconfigured server bootstrap, HMR/dev teardown leaving mastra undefined).

Common situations: Custom server setups not passing mastra to the route handlers; plugin/middleware ordering issues; broken mastra build/registration so the instance never registers; test harnesses invoking handlers without a mastra instance.

Related errors

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