vercel/ai · error · HarnessCapabilityUnsupportedError

Harness 'codex' does not support built-in tool approval requ

Error message

Harness 'codex' does not support built-in tool approval requests; use permissionMode: 'allow-all'.

What it means

The codex harness only supports permissionMode 'allow-all'; it cannot surface built-in tool approval prompts. Any other permissionMode (e.g. 'default', 'ask') passed in start options throws HarnessCapabilityUnsupportedError, directing users to allow-all.

Source

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

    harnessId: 'codex',
    builtinTools: CODEX_BUILTIN_TOOLS,
    supportsBuiltinToolApprovals: false,
    lifecycleStateSchema: codexResumeStateSchema,
    getBootstrap: getCodexBootstrap,
    doStart: async startOpts => {
      const model = settings.model ?? DEFAULT_CODEX_MODEL;
      if (startOpts.builtinToolFiltering != null) {
        throw new HarnessCapabilityUnsupportedError({
          message:
            "Harness 'codex' does not support built-in tool filtering controls.",
          harnessId: 'codex',
        });
      }
      if (
        startOpts.permissionMode != null &&
        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:

View on GitHub (pinned to 69428b1f8b)

Solutions

Pass permissionMode: 'allow-all' (or omit it if allow-all is the default).
Enforce approvals outside the harness (e.g. review transcripts, sandbox restrictions) since codex cannot ask.
Use a different harness if interactive tool approvals are required.

Example fix

// before
harness.start({ permissionMode: 'default' });
// after
harness.start({ permissionMode: 'allow-all' });

Defensive patterns

Strategy: validation

Validate before calling

if (startOpts?.permissionMode != null && startOpts.permissionMode !== 'allow-all') {
  throw new Error('codex harness requires permissionMode: allow-all');
}

Try / catch

try {
  await harness.start(startOpts);
} catch (e) {
  if (/does not support built-in tool approval/.test(String(e?.message))) {
    // retry with permissionMode: 'allow-all'
  } else throw e;
}

Prevention

Omit permissionMode (or use 'allow-all') for codex
Branch start options per harness when sharing config
Implement approvals outside the harness if needed

When it happens

Trigger: Calling createCodex(...).start({ permissionMode: 'default' }) or any value other than 'allow-all' (or undefined).

Common situations: Reusing the same start options across harnesses where other harnesses support approval flows; enabling stricter permissions for production while using codex.

Related errors

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