vercel/ai · error · HarnessCapabilityUnsupportedError

Harness 'codex' does not support built-in tool filtering con

Error message

Harness 'codex' does not support built-in tool filtering controls.

What it means

The codex harness declares supportsBuiltinToolFiltering: false. If doStart receives startOpts.builtinToolFiltering (an attempt to enable/disable built-in tools like web search), it throws HarnessCapabilityUnsupportedError because the harness cannot forward those controls to the Codex CLI.

Source

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

  sandboxCredentialEnvironment: z.record(z.string(), z.string()).optional(),
});

type CodexBridgeCoords = z.infer<typeof codexBridgeCoordsSchema>;

export function createCodex(
  settings: CodexHarnessSettings = {},
): HarnessV1<typeof CODEX_BUILTIN_TOOLS> {
  return {
    specificationVersion: 'harness-v1',
    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);

View on GitHub (pinned to 69428b1f8b)

Solutions

Remove builtinToolFiltering from the start options when using the codex harness.
Control built-in tools via Codex-native configuration (config.toml / CLI flags) instead.
Feature-detect harness capabilities before setting filtering options.

Example fix

// before
harness.start({ builtinToolFiltering: { exclude: ['web_search'] } });
// after
harness.start({}); // configure built-in tools in codex config instead

Defensive patterns

Strategy: validation

Validate before calling

if (startOpts?.builtinToolFiltering != null) {
  throw new Error('codex harness: remove builtinToolFiltering from start options');
}

Try / catch

try {
  await harness.start(startOpts);
} catch (e) {
  if (/does not support built-in tool filtering/.test(String(e?.message))) {
    // retry without builtinToolFiltering
  } else throw e;
}

Prevention

Check harness capability flags before setting start options
Keep harness-specific options out of shared start-option builders
Configure built-in tools through codex config files instead

When it happens

Trigger: Calling createCodex(...).start({ builtinToolFiltering: {...} }) or passing builtinToolFiltering in start options with any non-null value.

Common situations: Shared harness abstraction code that uniformly passes builtinToolFiltering to every harness; switching from a harness that supports filtering (e.g. claude) to codex without changing start options.

Related errors

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