vercel/ai · error · TypeError

Code mode interrupt payload must include a string kind.

Error message

Code mode interrupt payload must include a string kind.

What it means

After confirming the interrupt payload is a plain object, requestCodeModeInterrupt requires a non-empty string 'kind' property. The kind discriminates interrupt types on the host side (e.g. tool approval vs custom interrupts), so a missing or empty kind cannot be routed and a TypeError is thrown.

Source

Thrown at packages/code-mode/src/host-interrupt.ts:15

import { getHostFunctionContext } from 'run';
import type { CodeModeInterruptPayload } from './types.js';

export function requestCodeModeInterrupt<
  TPayload extends CodeModeInterruptPayload,
>(payload: TPayload): never {
  if (
    typeof payload !== 'object' ||
    payload === null ||
    Array.isArray(payload)
  ) {
    throw new TypeError('Code mode interrupt payload must be an object.');
  }
  if (typeof payload.kind !== 'string' || payload.kind.length === 0) {
    throw new TypeError(
      'Code mode interrupt payload must include a string kind.',
    );
  }
  return getHostFunctionContext().interrupt(payload);
}

View on GitHub (pinned to 69428b1f8b)

Solutions

Add a non-empty string kind to the payload object, e.g. { kind: 'approval', … }.
Check for accidental kind: undefined from object spread order and fix property ordering.
If the kind is dynamic, guard it: if (!kind) throw before calling requestCodeModeInterrupt.

Example fix

// before
requestCodeModeInterrupt({ ...details });
// after
requestCodeModeInterrupt({ kind: 'user-confirmation', ...details });

Defensive patterns

Strategy: validation

Validate before calling

function hasKind(p: object): boolean {
  return typeof (p as { kind?: unknown }).kind === 'string' && (p as { kind: string }).kind.length > 0;
}
if (!hasKind(payload)) payload = { kind: 'default', ...payload };

Type guard

function hasNonEmptyKind(v: unknown): v is { kind: string } {
  return typeof v === 'object' && v !== null && typeof (v as { kind?: unknown }).kind === 'string' && (v as { kind: string }).kind.length > 0;
}

Prevention

Put kind first in the payload literal so spread order can't overwrite it with undefined.
Define a union of allowed kind values in one shared constant.
Add a unit test that every code path calling requestCodeModeInterrupt includes kind.

When it happens

Trigger: Calling requestCodeModeInterrupt({}) or { kind: '' } from code-mode sandbox code — an object that omits kind or sets it to an empty/non-string value.

Common situations: Refactoring code that renamed the discriminating field (e.g. type instead of kind), spreading a payload where kind was overwritten by undefined via { kind: undefined, ...rest }, or LLM-generated code forgetting the kind field entirely.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/e34301b0945751ad. Report an issue: GitHub.