{"record":{"id":"52d2f1b8d2c38729","repo":"CopilotKit/CopilotKit","slug":"channel-opts-name-unnamed-must-registe","errorCode":null,"errorMessage":"channel \"${opts.name ?? \"(unnamed)\"}\" must register onMention or onMessage before activation","messagePattern":"channel \"(.+?)\" must register onMention or onMessage before activation","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/channels-core/src/create-channel.ts","lineNumber":1366,"sourceCode":"          );\n        }\n        adapters.push(adapter);\n      },\n      async start() {\n        // Idempotent: a second start() must not re-resolve the backend and\n        // rebuild Transcripts/Telemetry/ActionRegistry or re-call adapter.start()\n        // — with a MemoryStore that wipes all lock/dedup/transcript/action state,\n        // and real adapters would connect/port-bind twice.\n        if (started) return;\n        if (componentConfigurationError) throw componentConfigurationError;\n        if (\n          adapters.some(\n            (adapter) => adapter.capabilities.supportsMessageEvents,\n          ) &&\n          mentionHandlers.length === 0 &&\n          messageHandlers.length === 0\n        ) {\n          throw new Error(\n            `channel \"${opts.name ?? \"(unnamed)\"}\" must register onMention or onMessage before activation`,\n          );\n        }\n        started = true;\n        // Resolve persistence now that all adapters (including any attached via\n        // addAdapter) are known, then build the transcript store, action\n        // registry, and register components against it.\n        backend = resolveBackend(cfg.adapter, adapters);\n        transcripts = new Transcripts(backend, cfg.transcripts ?? {});\n        const tel = new ChannelTelemetry({\n          backend,\n          packageName: pkg.name,\n          packageVersion: pkg.version,\n        });\n        telemetry = tel;\n        const registryInstance = new ActionRegistry({\n          store:\n            opts.actionStore ??","sourceCodeStart":1348,"sourceCodeEnd":1384,"githubUrl":"https://github.com/CopilotKit/CopilotKit/blob/68fbe97d87420bd84e8196965c71bd6e394a3f7a/packages/channels-core/src/create-channel.ts#L1348-L1384","documentation":"A channel whose adapters support message events (supportsMessageEvents) is considered dead if it registers no onMention and no onMessage handlers — it would receive messages and do nothing. start() throws this guard so the runtime reports failure instead of a silently idle channel.","triggerScenarios":"Creating a channel with a message-capable adapter (e.g. Slack/Discord) but only registering onCommand or onAction handlers; forgetting to copy handler registration lines when refactoring a channel; registering handlers after start.","commonSituations":"Commands-only bots on messaging platforms; refactoring that moves onMessage into a conditionally-skipped branch; empty placeholder channels left in config.","solutions":["Register at least one channel.onMessage(...) or channel.onMention(...) handler before start","If the channel is intentionally passive, use an adapter without supportsMessageEvents (or remove it)","Give the channel a (possibly temporary) name to make the error message identify it"],"exampleFix":"// before\nconst ch = createChannel({ name: \"bot\", identifyUser: \"platform\", agent });\nch.onCommand(\"help\", handler);\nawait runner.start(ch); // throws\n\n// after\nch.onMessage(thread => { /* ... */ });\nawait runner.start(ch);","handlingStrategy":"validation","validationCode":"if (channel.commandNames.length > 0 && !hasMessageHandlers(channel)) {\n  channel.onMessage(() => {}); // or add a real handler\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Register onMessage/onMention in the same setup function that builds the channel","Add a startup lint: message-capable channels require at least one message handler"],"tags":["handlers","onmessage","onmention","start","channel"],"backgroundTag":"missing-event-handler","analyzedSha":"68fbe97d87420bd84e8196965c71bd6e394a3f7a","analyzedAt":"2026-08-27T04:03:26.537Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}