vercel/ai · error · HarnessCapabilityUnsupportedError

The codex harness requires an explicit `port` when using a b

Error message

The codex harness requires an explicit `port` when using a basic sandbox session.

What it means

validateBasicSandboxSettings checks settings for 'basic' sandbox sessions (those without getPortEndpoint). Such sessions cannot derive an endpoint, so the harness demands an explicit `port`; if port is null it throws HarnessCapabilityUnsupportedError. (A following check similarly requires portEndpoint.)

Source

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

    harnessId: 'codex',
    message:
      'The codex harness needs a TCP port exposed by the sandbox. ' +
      'Create the sandbox with `ports: [<port>]` or pass `createCodex({ port })`.',
  });
}

function validateBasicSandboxSettings({
  sandboxSession,
  port,
  portEndpoint,
}: {
  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
  port: number | undefined;
  portEndpoint: HarnessV1PortEndpoint | undefined;
}): void {
  if ('getPortEndpoint' in sandboxSession) return;
  if (port == null) {
    throw new HarnessCapabilityUnsupportedError({
      harnessId: 'codex',
      message:
        'The codex harness requires an explicit `port` when using a basic sandbox session.',
    });
  }
  if (portEndpoint == null) {
    throw new HarnessCapabilityUnsupportedError({
      harnessId: 'codex',
      message:
        'The codex harness requires an explicit `portEndpoint` when using a basic sandbox session.',
    });
  }
}

async function resolveBridgeEndpoint({
  sandboxSession,
  override,
  port,

View on GitHub (pinned to 69428b1f8b)

Solutions

Pass an explicit port: createCodex({ port: 4096, sandboxSession }).
Also provide portEndpoint if required by the following validation step.
Use a sandbox session implementing getPortEndpoint so the port can be resolved automatically.

Example fix

// before
createCodex({ sandboxSession: basicSession }); // basic session, no port
// after
createCodex({ sandboxSession: basicSession, port: 4096, portEndpoint: 'sandbox.example.com:4096' });

Defensive patterns

Strategy: validation

Validate before calling

if (!('getPortEndpoint' in sandboxSession) && (settings.port == null || settings.portEndpoint == null)) {
  throw new Error('basic sandbox sessions require explicit port and portEndpoint');
}

Type guard

function isFullSandboxSession(s) {
  return typeof s === 'object' && s !== null && 'getPortEndpoint' in s;
}

Try / catch

try {
  const codex = createCodex(settings);
} catch (e) {
  if (/requires an explicit `port`/.test(String(e?.message))) {
    // add port (and portEndpoint) to settings and rebuild
  } else throw e;
}

Prevention

Provide port and portEndpoint whenever using a basic sandbox session
Prefer full sandbox sessions implementing getPortEndpoint
Validate sandbox settings at construction time, not at start

When it happens

Trigger: createCodex with a sandboxSession lacking getPortEndpoint and neither `port` nor (later) `portEndpoint` provided in settings.

Common situations: Using a basic sandbox session type but forgetting createCodex({ port }); code that worked with a full sandbox session (with getPortEndpoint) reused with a basic session.

Related errors

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