What causes "Code mode interrupt payload must be an object." in vercel/ai?

Ensure the value passed to requestCodeModeInterrupt is a plain object literal, e.g. { kind: 'confirm', … }.

vercel/ai · error · TypeError

Code mode interrupt payload must be an object.

Error message

Code mode interrupt payload must be an object.

What it means

requestCodeModeInterrupt lets sandboxed code-mode programs suspend execution and surface an interrupt payload to the host. Before delegating to the host interrupt mechanism, it validates that the payload is a plain, non-null, non-array object. A TypeError is thrown when the payload fails this shape check, because downstream continuation signing and matching require a structured object payload.

Source

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

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

Ensure the value passed to requestCodeModeInterrupt is a plain object literal, e.g. { kind: 'confirm', … }.
If the payload is computed, add a fallback: payload ?? { kind: 'default' } before calling the interrupt.
Wrap arrays or scalars in an object field (e.g. { kind: 'batch', items }) instead of passing them directly.

Example fix

// before
requestCodeModeInterrupt(input?.confirmation);
// after
const payload = input?.confirmation;
if (payload == null || typeof payload !== 'object' || Array.isArray(payload)) {
  throw new Error('missing confirmation payload');
}
requestCodeModeInterrupt({ kind: 'confirm', ...payload });

Defensive patterns

Strategy: validation

Validate before calling

function isValidInterruptPayload(p: unknown): boolean {
  return typeof p === 'object' && p !== null && !Array.isArray(p);
}
// before calling: if (!isValidInterruptPayload(payload)) fix or throw;

Type guard

function isInterruptPayload(v: unknown): v is { kind: string; [k: string]: unknown } {
  return typeof v === 'object' && v !== null && !Array.isArray(v) && typeof (v as any).kind === 'string' && (v as any).kind.length > 0;
}

Prevention

Always build interrupt payloads as object literals with an explicit kind field.
Type the payload with CodeModeInterruptPayload so TypeScript rejects scalars and arrays.
Avoid JSON.parse of untrusted data directly into the payload without validation.

When it happens

Trigger: Calling requestCodeModeInterrupt(null), requestCodeModeInterrupt(undefined), requestCodeModeInterrupt([…]), or requestCodeModeInterrupt('string') / a number/boolean from inside code-mode JS, instead of passing an object with a string kind field.

Common situations: Generated or hand-written sandbox code that builds the payload dynamically and ends up with null/undefined (e.g. a JSON.parse failure or a variable that was never assigned), or that mistakenly passes an array of payloads rather than a single payload object.

Related errors

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