{"record":{"id":"2d24820def46335e","repo":"mastra-ai/mastra","slug":"agent-agentid-not-found-2d2482","errorCode":null,"errorMessage":"Agent \"${agentId}\" not found","messagePattern":"Agent \"(.+?)\" not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/channels.ts","lineNumber":84,"sourceCode":"      resource: 'agents',\n      resourceId: agentId,\n      action: 'edit',\n      record: stored,\n    });\n    return;\n  }\n\n  // Not in stored-agents (or storage doesn't support it). Check the runtime\n  // registry for a code-defined agent.\n  const codeDefined = mastra.getAgentById(agentId);\n  if (codeDefined) {\n    // Code-defined agents have no owner/ACL — route's requiresAuth /\n    // requiresPermission is the gate. Pass-through.\n    return;\n  }\n\n  if (action === 'connect') {\n    throw new HTTPException(404, { message: `Agent \"${agentId}\" not found` });\n  }\n\n  // Disconnect against an unknown agentId = orphan cleanup (stored agent was\n  // deleted but the channel installation row is still around). Allow it, but\n  // gate on channels:write so this isn't an \"any authenticated user\" backdoor.\n  // Follow the same no-auth-configured pass-through as assertWriteAccess.\n  const callerAuthorId = getCallerAuthorId(requestContext);\n  if (!callerAuthorId && !requestContext.get(MASTRA_USER_KEY)) return;\n  if (hasAdminBypass(requestContext, 'channels')) return;\n  if (hasScopedPermission({ requestContext, resource: 'channels', action: 'write' })) return;\n\n  throw new HTTPException(404, { message: 'Not found' });\n}\n\n// ============================================================================\n// Route Definitions\n// ============================================================================\n","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/channels.ts#L66-L102","documentation":"assertChannelAgentWriteAccess checks ACL/ownership before connecting or disconnecting a channel to an agent. For unknown stored agents, connect is refused with a 404 ('Agent \"X\" not found'), while disconnect is allowed as orphan cleanup (the stored agent was deleted but the installation row persists) but gated on channels:write. Code-defined agents pass through because their gate is the route's auth/permission checks.","triggerScenarios":"CONNECT_CHANNEL_ROUTE called with an agentId that is neither a stored (DB) agent nor a code-defined agent on the instance — e.g. the agent was deleted, the ID is wrong, or the agent exists on another deployment.","commonSituations":"Client caches an agentId after the agent was deleted; connecting a channel to a not-yet-created agent; ID casing/typo; environment mismatch (staging agentId used against production).","solutions":["Verify the agentId exists (list stored agents or check your code-defined agents) before connecting.","Create the agent first if it does not exist, then connect the channel.","Re-fetch the current agent ID after any delete/recreate, rather than reusing a stored ID.","For orphaned installations (agent deleted), use disconnect with channels:write permission to clean up the row."],"exampleFix":"// before\nawait fetch(`/api/channels/slack/connect`, { method: 'POST', body: JSON.stringify({ agentId: 'old-agent' }) });\n\n// after\nconst agents = await fetch('/api/agents').then(r => r.json());\nif (!agents.some(a => a.id === agentId)) throw new Error(`Agent ${agentId} does not exist — create it first`);","handlingStrategy":"validation","validationCode":"const agents = await listAgents();\nif (!agents.some(a => a.id === agentId)) {\n  throw new Error(`Agent \"${agentId}\" does not exist — create it before connecting a channel`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await connectChannel(platform, agentId);\n} catch (e) {\n  if (e.status === 404 && e.message.startsWith('Agent \"')) {\n    // refresh agent list; the stored agent was likely deleted\n  } else throw e;\n}","preventionTips":["Fetch agent IDs fresh from the agents endpoint before connecting channels.","Invalidate cached agent IDs on agent delete/recreate.","Require channels:write permission for disconnect-based orphan cleanup flows.","Check both stored and code-defined agent sources when validating IDs client-side."],"tags":["http-404","channels","agents","acl"],"backgroundTag":"resource-not-found-404","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}