{"record":{"id":"b05f62c481aca878","repo":"mastra-ai/mastra","slug":"agent-controller-controllerid-not-found","errorCode":null,"errorMessage":"agent controller \"${controllerId}\" not found","messagePattern":"agent controller \"(.+?)\" not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/agent-controller.ts","lineNumber":73,"sourceCode":"} satisfies Record<ReservedThreadMetadataKey, true>;\n\nfunction isReservedThreadMetadataKey(key: string): boolean {\n  return Object.hasOwn(RESERVED_THREAD_METADATA_KEYS, key) || key.startsWith('modeModelId_');\n}\n\n/**\n * Resolves a controller by id via the canonical `mastra.getAgentController`\n * accessor, throwing a 404 if no controller is registered under that id.\n */\nfunction getAgentControllerOrThrow(\n  mastra: {\n    getAgentController?: (id: string) => AgentController<any> | undefined;\n  },\n  controllerId: string,\n): AgentController<any> {\n  const controller = mastra.getAgentController?.(controllerId);\n  if (!controller) {\n    throw new HTTPException(404, { message: `agent controller \"${controllerId}\" not found` });\n  }\n  return controller;\n}\n\nasync function getSession(\n  controller: AgentController<any>,\n  resourceId: string,\n  options?: { tags?: Record<string, string>; scope?: string; threadId?: string },\n  requestContext?: RequestContext,\n): Promise<Session<any>> {\n  await controller.init();\n  const { tags, scope, threadId } = options ?? {};\n  // Scoped sessions are independent sessions over the same resource (e.g. one\n  // per git worktree), so qualify the stable session id with the scope to keep\n  // their identities distinct as well. An exact thread binding doubles as the\n  // stable session id when supplied.\n  const id = threadId ?? (scope ? `${resourceId}::${scope}` : resourceId);\n  return controller.createSession({ resourceId, id, ownerId: controller.id, tags, scope, threadId, requestContext });","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/agent-controller.ts#L55-L91","documentation":"getAgentControllerOrThrow resolves an agent controller via `mastra.getAgentController(controllerId)` and throws HTTP 404 when the mastra instance has no controller registered under that id (or when getAgentController itself is undefined on the instance). It is the shared guard used by all agent-controller HTTP handlers.","triggerScenarios":"Any agent-controller endpoint (sessions, threads, objectives, messages) called with a `controllerId` path/body parameter that was never registered on the Mastra instance, e.g. `mastra.getAgentController` not configured or the controller removed/renamed in code.","commonSituations":"Playground UI or client referencing a controller that exists in another deployment/environment; controller deleted during refactor; server restarted with an updated agent definition so previously valid ids 404; forgetting to register controllers when constructing Mastra.","solutions":["Fix the controllerId in the request to one registered on the running Mastra instance.","Register the controller: configure `getAgentController` (and the controllers it returns) on your Mastra instance.","List available controllers from your server config and have the client pick from that instead of hardcoding ids.","Redeploy/restart so server code and client expectations reference the same controller set."],"exampleFix":"// before\nconst c = await api.getAgentControllerSession({ controllerId: 'coders' });\n// after\nconst c = await api.getAgentControllerSession({ controllerId: 'coder' }); // id registered via mastra.getAgentController","handlingStrategy":"validation","validationCode":"const controllers = await api.listAgentControllers();\nif (!controllers.some(c => c.id === controllerId)) {\n  throw new Error(`Controller '${controllerId}' is not registered on this server`);\n}","typeGuard":"function isKnownController(id: string, known: readonly string[]): id is string {\n  return known.includes(id);\n}","tryCatchPattern":"try {\n  return await api.getControllerSession({ controllerId });\n} catch (e) {\n  if (isHttpError(e) && e.status === 404 && e.message.includes('agent controller')) {\n    throw new Error(`Controller '${controllerId}' not found — check registration on the Mastra instance`);\n  }\n  throw e;\n}","preventionTips":["Derive controller ids from server metadata instead of hardcoding.","Keep controller registration and client constants in one module.","Add a startup check that every id referenced by your UI is registered."],"tags":["http-404","agent-controller","not-found","configuration"],"backgroundTag":"resource-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}