vercel/ai · error · HarnessCapabilityUnsupportedError

The Claude Code harness requires an explicit `port` when usi

Error message

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

What it means

For a 'basic' sandbox session — one that does not implement `getPortEndpoint` — the Claude Code harness cannot discover ports on its own, so an explicit `port` in `createClaudeCode` settings is mandatory. `validateBasicSandboxSettings` throws `HarnessCapabilityUnsupportedError` (harnessId `claude-code`) when the session lacks `getPortEndpoint` and `port` is null/undefined.

Source

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

    harnessId: 'claude-code',
    message:
      'The claude-code harness needs a TCP port exposed by the sandbox. ' +
      'Create the sandbox with `ports: [<port>]` or pass `createClaudeCode({ 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: 'claude-code',
      message:
        'The Claude Code harness requires an explicit `port` when using a basic sandbox session.',
    });
  }
  if (portEndpoint == null) {
    throw new HarnessCapabilityUnsupportedError({
      harnessId: 'claude-code',
      message:
        'The Claude Code 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` in `createClaudeCode` settings, e.g. `createClaudeCode({ sandboxSession, port: 3000 })`.
Switch to a `HarnessV1NetworkSandboxSession` that implements `getPortEndpoint` so the harness can resolve the port itself.
If the session does expose `ports`, note that `resolveBridgePort` may cover the no-override case — but for sessions lacking `getPortEndpoint` the validator still demands an explicit `port`, so provide one.
Check the session type before configuring: `if (!('getPortEndpoint' in session)) ensure port is set`.

Example fix

// before
createClaudeCode({ sandboxSession: basicSession });
// after
createClaudeCode({ sandboxSession: basicSession, port: 3000 });

Defensive patterns

Strategy: validation

Validate before calling

function assertBasicSandboxHasPort(sandboxSession, port) {
  if ('getPortEndpoint' in sandboxSession) return; // network session: fine
  if (port == null) {
    throw new TypeError('Basic sandbox sessions require an explicit createClaudeCode({ port })');
  }
}
assertBasicSandboxHasPort(sandboxSession, settings.port);

Type guard

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

Try / catch

try {
  return createClaudeCode({ sandboxSession, port, ...settings });
} catch (err) {
  if (err?.name === 'HarnessCapabilityUnsupportedError' && err.message.includes('requires an explicit `port`')) {
    throw new Error('Config error: add `port` to createClaudeCode for basic sandbox sessions', { cause: err });
  }
  throw err;
}

Prevention

Detect session type with 'getPortEndpoint' in session before configuring
Always supply port in createClaudeCode when using basic (non-network) sandbox sessions
Migrate to network sandbox sessions (getPortEndpoint) to avoid manual port wiring

When it happens

Trigger: `createClaudeCode({ sandboxSession, port: undefined })` where `sandboxSession` has no `getPortEndpoint` method (i.e. a `SandboxSession` rather than a `HarnessV1NetworkSandboxSession`).

Common situations: Using a plain/basic sandbox from a provider that does not implement the network-session interface; removing the `port` option during a refactor while still on a basic session; assuming port auto-discovery works for all session types (it only works with `getPortEndpoint` or a `ports`-bearing session).

Related errors

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