{"record":{"id":"5c34cc8edf955099","repo":"mastra-ai/mastra","slug":"agent-not-found","errorCode":null,"errorMessage":"Agent not found","messagePattern":"Agent not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/agents.ts","lineNumber":3620,"sourceCode":"// ============================================================================\n// Agent Skill Routes\n// ============================================================================\n\nexport const GET_AGENT_SKILL_ROUTE = createRoute({\n  method: 'GET',\n  path: '/agents/:agentId/skills/:skillName',\n  responseType: 'json',\n  pathParamSchema: agentSkillPathParams,\n  queryParamSchema: skillDisambiguationQuerySchema,\n  responseSchema: getAgentSkillResponseSchema,\n  summary: 'Get agent skill',\n  description: 'Returns details for a specific skill available to the agent (inline or workspace)',\n  tags: ['Agents', 'Skills'],\n  handler: async ({ mastra, agentId, skillName, path, requestContext }) => {\n    try {\n      const agent = agentId ? mastra.getAgentById(agentId) : null;\n      if (!agent) {\n        throw new HTTPException(404, { message: 'Agent not found' });\n      }\n\n      // Use the optional ?path= query param for disambiguation, otherwise fall back to name\n      const identifier = path ? decodeURIComponent(path) : skillName;\n\n      // Get the skill from the agent (searches both inline and workspace skills)\n      const skill = await agent.getSkill(identifier, { requestContext });\n      if (!skill) {\n        throw new HTTPException(404, { message: `Skill \"${identifier}\" not found` });\n      }\n\n      return {\n        name: skill.name,\n        description: skill.description,\n        license: skill.license,\n        compatibility: skill.compatibility,\n        metadata: skill.metadata,\n        path: skill.path,","sourceCodeStart":3602,"sourceCodeEnd":3638,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/agents.ts#L3602-L3638","documentation":"This HTTP 404 error is thrown when the skills detail route cannot resolve the `:agentId` path parameter to a registered agent: `mastra.getAgentById(agentId)` returns null/undefined. It means the agent does not exist in the current Mastra instance's registry.","triggerScenarios":"GET /api/agents/:agentId/skills/:skillName (or with ?path=) where agentId is not registered via mastra.getAgentById — wrong ID, agent not registered on the Mastra instance, or typo/case mismatch.","commonSituations":"Agent renamed or removed from mastra.getAgent registration; server instance differs from the one the client was built against; agentId casing or URL-encoding issues; dynamic agents not yet registered when the request arrives.","solutions":["Verify the agentId exists: call GET /api/agents and confirm the ID is listed.","Register the agent on the Mastra instance passed to the server (agents map in Mastra constructor or setLogger-adjacent registration).","Check for typos/case differences and correct URL-encoding of the agentId in the request path."],"exampleFix":"// before\nnew Mastra({ /* agents not registered */ });\n// after\nnew Mastra({ agents: { myAgent } });\n// request: /api/agents/myAgent/skills/my-skill","handlingStrategy":"validation","validationCode":"// resolve the agent id against the registry before calling the skills route\nconst agents = await (await fetch('/api/agents')).json();\nif (!agents.some(a => a.id === agentId)) {\n  throw new Error(`Agent \"${agentId}\" is not registered on this server`);\n}","typeGuard":"function isRegisteredAgent(agentId: string, agents: { id: string }[]): boolean {\n  return agents.some(a => a.id === agentId);\n}","tryCatchPattern":"try {\n  const res = await fetch(`/api/agents/${agentId}/skills/${skillName}`);\n  if (res.status === 404) throw new Error(`Agent \"${agentId}\" not found`);\n  return await res.json();\n} catch (e) { /* surface a friendly 'agent not found' message */ }","preventionTips":["Fetch the agent list at app startup and validate IDs before deeper calls.","Keep agent registration centralized so IDs are consistent.","URL-encode agent IDs in paths."],"tags":["http-404","agent-not-found","routing"],"backgroundTag":"resource-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}