CopilotKit/CopilotKit · error · Error

`ɵlearning` requires the Intelligence runtime (pass `intelli

Error message

`ɵlearning` requires the Intelligence runtime (pass `intelligence`); Learning Containers are not available in SSE mode.

What it means

Learning Containers (ɵlearning) require the Intelligence runtime for durability and delivery. The SSE-mode constructor has no such path; passing ɵlearning there would silently no-op, so it throws. Like channels, this only reaches JS/`as any` callers because the types forbid it.

Source

Thrown at packages/runtime/src/v2/runtime/core/runtime.ts:469

{
  readonly intelligence = undefined;
  readonly mode = RUNTIME_MODE_SSE;

  constructor(options: CopilotSseRuntimeOptions) {
    // Runtime guard mirroring the discriminated-union type: the SSE runtime has
    // no Intelligence delivery path, so `channels` cannot be honored here. The
    // type forbids it, but a JS / `as any` caller passing `{ agents, channels }`
    // would otherwise land here and have `channels` silently dropped — fail
    // loud instead.
    const channels = (options as { channels?: unknown[] }).channels;
    if (Array.isArray(channels) && channels.length > 0) {
      throw new Error(
        "`channels` requires the Intelligence runtime (pass `intelligence`); " +
          "Intelligence Channels are not available in SSE mode.",
      );
    }
    if ((options as { ɵlearning?: unknown }).ɵlearning !== undefined) {
      throw new Error(
        "`ɵlearning` requires the Intelligence runtime (pass `intelligence`); " +
          "Learning Containers are not available in SSE mode.",
      );
    }
    super(options, options.runner ?? new InMemoryAgentRunner());
  }
}

export class CopilotIntelligenceRuntime
  extends BaseCopilotRuntime
  implements CopilotIntelligenceRuntimeLike
{
  readonly intelligence: CopilotKitIntelligence;
  readonly identifyUser?: IdentifyUserCallback;
  readonly generateThreadNames: boolean;
  readonly lockTtlSeconds: number;
  readonly lockKeyPrefix?: string;
  readonly lockHeartbeatIntervalSeconds: number;

View on GitHub (pinned to 68fbe97d87)

Solutions

1. Pass intelligence to enable Learning Containers
2. Or delete ɵlearning from the options object when constructing the SSE runtime
3. Avoid `as any`; let the discriminated options types catch this at compile time

Example fix

// before
const opts = { agents, ɵlearning: { containerId: 'kb' } };
new CopilotRuntime(opts as any);
// after
new CopilotRuntime({ agents, intelligence: { apiKey, wsUrl }, ɵlearning: { containerId: 'kb' } });

if (!options.intelligence && options.ɵlearning !== undefined) {
  throw new Error('learning requires intelligence');
}

function isSseOptions(o: CopilotRuntimeOptions): o is CopilotSseRuntimeOptions {
  return (o as any).intelligence === undefined;
}

When it happens

Trigger: Constructing the SSE runtime (no intelligence option) with an ɵlearning property present, via plain JS, `as any`, or a shared options object.

Common situations: Migrating from Intelligence mode to SSE mode and leaving the learning config in place, or copying a full options blob from an Intelligence example into an SSE app.

Related errors

• `channels` requires the Intelligence runtime (pass `intellig
• Intelligence Runtime auto-wires its own `runner`; passing `r
• No default agent provided. Please provide a default agent in
• Intelligence Runtime `identifyUser` must be a callback
• Intelligence Runtime requires web `identifyUser`, at least o

AI-assisted analysis of CopilotKit/CopilotKit@68fbe97d87 (2026-08-27). Data as JSON: /api/errors/c7ea28720537bff0. Report an issue: GitHub.