mastra-ai/mastra · error · HTTPException

Agent with id ${agentId} not found

Error message

Agent with id ${agentId} not found

What it means

Thrown by getAgentFromSystem after attempting to resolve the agent both from the in-memory Mastra registry (getAgentById) and from stored-agent storage. A 404 meaning no registered or stored agent exists with the given id in this Mastra instance.

Source

Thrown at packages/server/src/server/handlers/agents.ts:976

        );
      }
    } catch (error) {
      logger.debug('Error applying stored overrides to code agent', error);
    }
  }

  // If still not found, try to get stored agent
  if (!agent) {
    logger.debug('Agent not found in code-defined agents, looking in stored agents', { agentId });
    try {
      agent = (await mastra.getEditor()?.agent.getById(agentId, versionOptions)) ?? null;
    } catch (error) {
      logger.debug('Error getting stored agent', error);
    }
  }

  if (!agent) {
    throw new HTTPException(404, { message: `Agent with id ${agentId} not found` });
  }

  return agent;
}

async function formatAgent({
  mastra,
  agent,
  requestContext,
  isStudio,
}: {
  mastra: Context['mastra'];
  agent: Agent;
  requestContext: RequestContext;
  isStudio: boolean;
}): Promise<SerializedAgent> {
  const description = agent.getDescription();
  let metadata: Record<string, unknown> | undefined;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the agent is registered in the Mastra instance (mastra.getAgentById(agentId)) or exists as a stored agent in the configured storage
2. Fix the agentId typo or update the client to use the current agent id
3. List available agents (GET /api/agents) and pick the correct id
4. Check the server/deployment you are calling actually registers this agent (env/flag differences)

Example fix

// before
new Mastra({ agents: { weatherAgent } }); // client calls 'weather'
await mastraClient.getAgent('weather').generate({ messages });
// after
new Mastra({ agents: { weather: weatherAgent } }); // id matches client
await mastraClient.getAgent('weather').generate({ messages });

// discover valid ids before calling
const { agents } = await fetch('/api/agents').then(r => r.json());
if (!(agentId in agents)) {
  throw new Error(`Agent '${agentId}' is not registered`);
}

function isRegisteredAgent(id: string, agents: Record<string, unknown>): id is keyof typeof agents & string {
  return Object.prototype.hasOwnProperty.call(agents, id);
}

try {
  const res = await client.getAgent(agentId).generate({ messages });
} catch (e) {
  if (isHttpException(e, 404) && String(e.message).includes('not found')) {
    // agent missing in this environment: list agents and warn about config drift
  }
}

When it happens

Trigger: POSTing to /agents/:agentId/generate (or stream/legacy variants) where agentId was never registered via new Mastra({ agents: {...} }) and no stored-agent record exists; the agent was renamed/removed; connecting to a server/deployment that doesn't include that agent.

Common situations: Typos in agent ids in client code; agents registered conditionally (feature flags/env) so they're missing in some environments; tests hitting a Mastra instance with a different agent set than production; stale client config after agent deletion.

Related errors

• Model "${modelId}" is not available. Available models: ${ids
• ClaudeSDKAgent resumeData must include either sessionId or c
• No workspace configured
• ACP connection is not initialized
• Model "${this.options.model}" is not available. Available mo

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