vercel/ai · error · HarnessCapabilityUnsupportedError

The Claude Code harness cannot use `mintBridgeToken` with a

Error message

The Claude Code harness cannot use `mintBridgeToken` with a sandbox session that does not expose an id.

What it means

When a Claude Code session runs inside a sandbox, `mintBridgeToken` requires the sandbox session to expose an `id`, because the minted bridge token is bound to that session id. If `mintBridgeToken` is set but the resolved `sandboxId` is null/undefined, `createClaudeCode` throws `HarnessCapabilityUnsupportedError` (harnessId `claude-code`).

Source

Thrown at packages/harness-claude-code/src/claude-code-harness.ts:855

    specificationVersion: 'harness-v1',
    harnessId: 'claude-code',
    builtinTools: CLAUDE_CODE_BUILTIN_TOOLS,
    supportsBuiltinToolApprovals: true,
    supportsBuiltinToolFiltering: true,
    lifecycleStateSchema: claudeCodeResumeStateSchema,
    getBootstrap: getClaudeCodeBootstrap,
    doStart: async startOpts => {
      const sandboxSession = startOpts.sandboxSession;
      const toolSafeSandboxSession =
        getRestrictedSandboxSession(sandboxSession);
      const sandboxId = 'id' in sandboxSession ? sandboxSession.id : undefined;
      validateBasicSandboxSettings({
        sandboxSession,
        port: settings.port,
        portEndpoint: settings.portEndpoint,
      });
      if (settings.mintBridgeToken != null && sandboxId == null) {
        throw new HarnessCapabilityUnsupportedError({
          harnessId: 'claude-code',
          message:
            'The Claude Code harness cannot use `mintBridgeToken` with a sandbox session that does not expose an id.',
        });
      }
      const defaultWorkingDirectory =
        await resolveSandboxDefaultWorkingDirectory({
          sandboxSession,
          abortSignal: startOpts.abortSignal,
        });
      const lifecycleState = startOpts.continueFrom ?? startOpts.resumeFrom;
      const isResume = lifecycleState != null;
      const isContinue = startOpts.continueFrom != null;
      const resumeData = isResume
        ? (lifecycleState?.data as {
            bridge?: ClaudeCodeBridgeCoords;
            sandboxCredentialEnvironment?: Record<string, string>;
            claudeSessionId?: string;

View on GitHub (pinned to 69428b1f8b)

Solutions

Recreate the sandbox session so it exposes a non-null `id` (request an id when creating the session), then pass it with `mintBridgeToken`.
Drop the `mintBridgeToken` option if bridge-token minting is not required for this session.
Use a sandbox session type/provider that supports ids (e.g. a network sandbox session exposing `getPortEndpoint`/id) instead of a basic session.
Check `sandboxSession.id` (or your provider's id accessor) before enabling `mintBridgeToken` and fail early with a clear message.

Example fix

// before
const session = await createBasicSandbox({ withId: false });
createClaudeCode({ sandboxSession: session, mintBridgeToken: true });
// after
const session = await createBasicSandbox({ withId: true });
createClaudeCode({ sandboxSession: session, mintBridgeToken: session.id != null });

Defensive patterns

Strategy: validation

Validate before calling

function assertMintBridgeTokenSupported(sandboxSession, settings) {
  if (settings.mintBridgeToken != null && (sandboxSession.id == null)) {
    throw new TypeError('mintBridgeToken requires a sandbox session with a non-null id');
  }
}
assertMintBridgeTokenSupported(sandboxSession, settings);

Type guard

function sandboxExposesId(session) {
  return typeof session === 'object' && session !== null && 'id' in session && session.id != null;
}

Try / catch

import { HarnessCapabilityUnsupportedError } from '@ai-sdk/harness';
try {
  return createClaudeCode(settings);
} catch (err) {
  if (HarnessCapabilityUnsupportedError.isInstance?.(err) || err?.name === 'HarnessCapabilityUnsupportedError') {
    if (err.message.includes('mintBridgeToken')) {
      return createClaudeCode({ ...settings, mintBridgeToken: undefined });
    }
  }
  throw err;
}

Prevention

Only enable mintBridgeToken for sandbox sessions created with an id
Check session.id != null before passing mintBridgeToken
Prefer network sandbox sessions that expose ids/endpoints for token workflows

When it happens

Trigger: `createClaudeCode({ sandboxSession, mintBridgeToken: true })` (or a mint function) where the sandbox session's id is null — i.e. a sandbox session created without an id or a session type that does not expose one — while the basic-sandbox checks in `validateBasicSandboxSettings` already passed.

Common situations: Connecting to a pre-existing/basic sandbox session that was created without requesting an id; upgrading the harness and newly enabling `mintBridgeToken` on an old session object; a sandbox provider returning a session without an id field.

Related errors

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