{"record":{"id":"b9ae61558952f188","repo":"mastra-ai/mastra","slug":"agentcontrollerchannels-is-not-bound-to-an-agentco","errorCode":null,"errorMessage":"AgentControllerChannels is not bound to an AgentController. Pass it via `channels` in AgentControllerConfig.","messagePattern":"AgentControllerChannels is not bound to an AgentController\\. Pass it via `channels` in AgentControllerConfig\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/channels/agent-controller-channels.ts","lineNumber":493,"sourceCode":"    if (!run) {\n      run = (async () => {\n        try {\n          await onSessionStart({ session, thread, requestContext });\n        } catch (error) {\n          // Best-effort by contract: a session that couldn't be configured\n          // still answers the message, on whatever defaults it was created\n          // with.\n          this.log('error', `Channel session-start hook failed for resourceId=${thread.resourceId}: ${error}`);\n        }\n      })();\n      this.sessionStartRuns.set(session, run);\n    }\n    await run;\n  }\n\n  private requireController(): AgentController<any> {\n    if (!this.controller) {\n      throw new Error(\n        'AgentControllerChannels is not bound to an AgentController. Pass it via `channels` in AgentControllerConfig.',\n      );\n    }\n    return this.controller;\n  }\n}\n","sourceCodeStart":475,"sourceCodeEnd":500,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/channels/agent-controller-channels.ts#L475-L500","documentation":"AgentControllerChannels requires a bound AgentController instance to operate. This plain Error is thrown when any channel method calls requireController() before the controller was injected. The binding happens only when the channels object is passed via `channels` in AgentControllerConfig.","triggerScenarios":"Instantiating AgentControllerChannels directly and calling methods (e.g. via `controller` accessor) without registering it on an AgentController through AgentControllerConfig.channels.","commonSituations":"Constructing the channels helper standalone in tests or scripts; forgetting to wire `channels` into the AgentController config; passing the channels object after the controller was already created without re-binding.","solutions":["Pass the AgentControllerChannels instance via `channels` in your AgentControllerConfig so it gets bound at construction.","Ensure you call channel methods on/after the controller binding, not on an unbound standalone instance.","In tests, construct the AgentController first and hand the channels object to its config instead of instantiating the channels class alone."],"exampleFix":"// before\nconst channels = new AgentControllerChannels();\nchannels.controller; // throws\n// after\nconst controller = new Agent({ ...config, channels: new AgentControllerChannels() });","handlingStrategy":"validation","validationCode":"if (!channelsInstance || channelsInstance.controller === undefined) throw new Error('AgentControllerChannels must be passed via AgentControllerConfig.channels');","typeGuard":"function isBound(ch: AgentControllerChannels): boolean { return !!ch.controller; }","tryCatchPattern":"try { requireBound(channels).someMethod(); } catch (e) { throw new Error('Wire channels into AgentControllerConfig first', { cause: e }); }","preventionTips":["Always construct channels via AgentControllerConfig, never standalone in app code","In tests, assert the binding right after controller construction","Call channel methods only through the controller, not on the raw channels object"],"tags":["channels","configuration","initialization-order"],"backgroundTag":"dependency-not-injected","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}