mastra-ai/mastra · critical · HTTPException

Mastra instance is required for conversations

Error message

Mastra instance is required for conversations

What it means

This is an internal server misconfiguration guard: the create-conversation route handler requires the Mastra instance from the server DI context, and throws HTTP 500 when it is undefined. Since Mastra is normally injected by the server runtime, a missing instance means the server was started without a Mastra instance or the handler context was built incorrectly.

Source

Thrown at packages/server/src/server/handlers/conversations.ts:59

    deleted: true,
  };
}

export const CREATE_CONVERSATION_ROUTE = createRoute({
  method: 'POST',
  path: '/v1/conversations',
  responseType: 'json',
  bodySchema: createConversationBodySchema,
  responseSchema: conversationObjectSchema,
  summary: 'Create a conversation',
  description: 'Creates a new thread-backed conversation for agent-backed Responses API requests',
  tags: ['Responses'],
  requiresAuth: true,
  requiresPermission: MastraFGAPermissions.AGENTS_CREATE,
  handler: async ({ mastra, requestContext, agent_id, conversation_id, resource_id, title, metadata }) => {
    try {
      if (!mastra) {
        throw new HTTPException(500, { message: 'Mastra instance is required for conversations' });
      }

      const agent = await getAgentFromSystem({ mastra, agentId: agent_id });
      const memory = await agent.getMemory({ requestContext });
      if (!memory) {
        throw new HTTPException(400, { message: `Agent "${agent.id}" does not have memory configured` });
      }
      if (!(await getAgentMemoryStore({ agent, requestContext }))) {
        throw new HTTPException(400, { message: `Memory storage is not configured for agent "${agent.id}"` });
      }

      const threadId = conversation_id ?? randomUUID();
      const resourceId = getEffectiveResourceId(requestContext, resource_id) ?? threadId;
      const thread = await memory.createThread({
        threadId,
        resourceId,
        title,
        metadata,

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Ensure the server is created with a Mastra instance (pass it to the server constructor / context binding) and restart
  2. If mounting handlers manually, set mastra on the request context exactly as the generated server does
  3. Check server startup logs for Mastra initialization errors and fix the underlying init failure
  4. Verify the deployment includes the mastra instance module and it is not stripped by the bundler

Example fix

// before
const app = createServerRoutes({}); // mastra missing
// after
const mastra = new Mastra({ agents: { myAgent } });
const app = createServerRoutes({ mastra });
Defensive patterns

Strategy: validation

Validate before calling

// at server bootstrap
if (!mastra) {
  throw new Error('Server misconfigured: Mastra instance was not provided to the server context');
}

Type guard

function hasMastra(ctx: { mastra?: unknown }): ctx is { mastra: Mastra } {
  return !!ctx.mastra && typeof (ctx.mastra as Mastra).getAgents === 'function';
}

Try / catch

try {
  const conv = await client.createConversation({ agent_id, resource_id });
} catch (e) {
  if (e.status === 500 && /Mastra instance is required/.test(e.message)) {
    // server-side DI bug: alert/fix server bootstrap, not the request
  }
  throw e;
}

Prevention

When it happens

Trigger: POSTing to the conversations (Responses) route when the `mastra` value on the handler context is undefined — server constructed without a Mastra instance, custom server embedding that omits mastra in context, or broken DI wiring in a self-hosted/Hono mount.

Common situations: Embedding the Mastra server handlers in a custom Hono app and forgetting to pass the Mastra instance into the context; server bootstrap failure where mastra is not registered; deploying a build where the mastra initialization module was tree-shaken or failed silently.

Related errors

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