vercel/ai · error · HarnessCapabilityUnsupportedError

The codex harness cannot use `mintBridgeToken` with a sandbo

Error message

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

What it means

When settings.mintBridgeToken is configured, the codex harness must know the sandbox session id to mint a bridge token scoped to that session. If the resolved sandboxId is null (the sandbox session does not expose an id), it throws HarnessCapabilityUnsupportedError.

Source

Thrown at packages/harness-codex/src/codex-harness.ts:236

        startOpts.permissionMode !== 'allow-all'
      ) {
        throw new HarnessCapabilityUnsupportedError({
          message:
            "Harness 'codex' does not support built-in tool approval requests; use permissionMode: 'allow-all'.",
          harnessId: 'codex',
        });
      }
      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: 'codex',
          message:
            'The codex 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 && typeof lifecycleState?.data === 'object'
          ? (lifecycleState.data as {
              threadId?: unknown;
              turnConfigurationFingerprint?: unknown;

View on GitHub (pinned to 69428b1f8b)

Solutions

Use a sandbox session that exposes an `id` property when mintBridgeToken is configured.
Drop the mintBridgeToken setting if the sandbox does not track session ids.
Create the sandbox through the supported provider API so a session id is assigned.

Example fix

// before
createCodex({ sandboxSession: { getPortEndpoint }, mintBridgeToken: true });
// after
createCodex({ sandboxSession: { id: 'sess_123', getPortEndpoint }, mintBridgeToken: true });

Defensive patterns

Strategy: validation

Validate before calling

if (settings.mintBridgeToken != null && (sandboxSession == null || !('id' in sandboxSession) || sandboxSession.id == null)) {
  throw new Error('mintBridgeToken requires a sandbox session with an id');
}

Type guard

function hasSessionId(s) {
  return typeof s === 'object' && s !== null && 'id' in s && typeof s.id === 'string' && s.id.length > 0;
}

Try / catch

try {
  const session = await codex.start({});
} catch (e) {
  if (/mintBridgeToken.*does not expose an id/.test(String(e?.message))) {
    // recreate sandbox with an id-bearing session or drop mintBridgeToken
  } else throw e;
}

Prevention

Only enable mintBridgeToken with provider-managed sandbox sessions
Assert session id presence in sandbox factory code
Avoid hand-rolled SandboxSession stubs in production paths

When it happens

Trigger: createCodex({ mintBridgeToken: ... }) combined with a sandboxSession object that lacks an id property, during doStart validation.

Common situations: Using a minimal/custom sandbox session implementation that omits id; constructing a SandboxSession stub in tests without an id while enabling bridge token minting.

Related errors

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