mastra-ai/mastra · error · HTTPException

Agent not found

Error message

Agent not found

What it means

Thrown by `getMemoryFromContext` when the given agentId cannot be resolved on the Mastra instance and the caller did not set `allowMissingAgent`. The handler needs the agent to obtain its Memory, so an unresolvable agent is a hard 404.

Source

Thrown at packages/server/src/server/handlers/memory.ts:252

        try {
          const subAgents = await ag.listAgents({ requestContext });

          if (subAgents[agentId]) {
            agent = subAgents[agentId];
            break;
          }
        } catch (error) {
          logger.debug('Error getting agent from agent', error);
        }
      }
    }

    if (!agent) {
      if (allowMissingAgent) {
        logger.debug('Agent not found in any resolution tier, returning null for storage fallback', { agentId });
        return null;
      }
      throw new HTTPException(404, { message: 'Agent not found' });
    }
  }

  if (agent) {
    return await agent?.getMemory({
      requestContext,
    });
  }
}

/**
 * Gets the storage from context, used as a fallback when agent memory can't be resolved.
 * This covers both cases where no agentId is provided and where the agentId refers to
 * a stored agent whose memory instance can't be hydrated (e.g. no editor configured).
 */
function getStorageFromContext({ mastra }: Pick<MemoryContext, 'mastra'>): MastraStorage | undefined {
  return mastra.getStorage();
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify agentId against the agents actually registered on the Mastra instance (`mastra.getAgents()` keys).
2. Register the agent (or fix the registration condition) so it exists in the target environment.
3. Fix any typo/renamed id in the client or URL.
4. If a storage-fallback is acceptable without an agent, use the code path that passes `allowMissingAgent: true`.

Example fix

// before
const mem = await getMemoryFromContext({ mastra, agentId: 'my-agnt' }) // 404
// after
const mem = await getMemoryFromContext({ mastra, agentId: 'my-agent' })

const agents = mastra.getAgents?.() ?? {};
if (!agents[agentId]) throw new Error(`Agent '${agentId}' not registered. Available: ${Object.keys(agents).join(', ')}`);

function agentExists(mastra: Mastra, agentId: string): boolean {
  return typeof mastra.getAgent === 'function' && !!mastra.getAgent(agentId);
}

try {
  const memory = await getMemoryFromContext({ mastra, agentId, requestContext });
} catch (e) {
  if (isHttpError(e, 404) && e.message === 'Agent not found') {
    // fall back to default memory or surface a clear 'unknown agent' UI error
  }
  throw e;
}

When it happens

Trigger: Any memory route that resolves an agent (e.g. GET memory for agent) where `getAgentById`/agent lookup returns undefined: unknown agentId, agent registered under a different id, or agent missing on the deployed Mastra instance.

Common situations: Typo in agentId in the request; playground pointed at a Mastra instance without that agent; agents conditionally registered per environment; renamed agent after UI bookmarks stored the old id.

Related errors

• thread "${requestedThreadId}" not found
• Thread not found
• Source thread not found
• Model "${modelId}" is not available. Available models: ${ids
• ACP connection is not initialized

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