vercel/ai · error · HarnessCapabilityUnsupportedError

The Claude Code harness requires an explicit `portEndpoint`

Error message

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

What it means

The Claude Code harness needs to connect to a bridge server over WebSocket inside the sandbox. When the provided sandbox session is a 'basic' one that does not implement `getPortEndpoint`, the harness cannot resolve an endpoint itself, so it demands an explicit `portEndpoint` in the createClaudeCode config. This fail-fast validation (validateBasicSandboxSettings) runs at creation time and throws HarnessCapabilityUnsupportedError instead of failing later at connection time.

Source

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

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,
}: {
  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
  override: HarnessV1PortEndpoint | undefined;
  port: number;
}): Promise<HarnessV1PortEndpoint> {
  if (override != null) return override;
  if ('getPortEndpoint' in sandboxSession) {

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Pass an explicit `portEndpoint` in createClaudeCode options (e.g. `{ url: 'wss://host:port/path' }` for the bridge WebSocket).
2. Use a network sandbox session that implements `getPortEndpoint` so the endpoint can be derived from the port.
3. If your sandbox exposes ports, ensure both `port` and `portEndpoint` are provided together when using a basic session.
4. Check the harness README for the expected HarnessV1PortEndpoint shape and construct it from your sandbox's forwarded URL.

Example fix

// before
const harness = createClaudeCode({ sandboxSession: basicSession, port: 8080 });
// after
const harness = createClaudeCode({
  sandboxSession: basicSession,
  port: 8080,
  portEndpoint: { url: 'wss://sandbox.example.com/8080/ws' },
});

function canUseBasicSandbox(session, opts) {
  const hasGetPortEndpoint = session && typeof session.getPortEndpoint === 'function';
  return hasGetPortEndpoint || (opts.port != null && opts.portEndpoint != null);
}
if (!canUseBasicSandbox(sandboxSession, config)) {
  throw new Error('Provide portEndpoint (and port) or use a network sandbox with getPortEndpoint');
}

function hasPortEndpoint(
  s: SandboxSession,
): s is SandboxSession & { getPortEndpoint: (a: { port: number; protocol: 'ws' }) => Promise<HarnessV1PortEndpoint> } {
  return 'getPortEndpoint' in s && typeof (s as any).getPortEndpoint === 'function';
}

try {
  const harness = createClaudeCode({ sandboxSession, port, portEndpoint });
} catch (e) {
  if (HarnessCapabilityUnsupportedError.isInstance(e) && e.message.includes('portEndpoint')) {
    // fall back to a network sandbox or set portEndpoint
  }
  throw e;
}

When it happens

Trigger: Calling createClaudeCode with a sandbox session lacking a `getPortEndpoint` method while `portEndpoint` is undefined (even if `port` is set). Caught by validateBasicSandboxSettings before the harness session is created.

Common situations: Using a custom or minimal SandboxSession implementation that only exposes `ports` but not `getPortEndpoint`; passing `port` but forgetting `portEndpoint`; upgrading the harness package where basic sandbox sessions are no longer auto-resolved.

Related errors

• 'HarnessAgent: `sandboxConfig.workDir` must not contain NUL.
• 'HarnessAgent: `sandboxConfig.workDir` must be relative.'
• prepareSandboxForHarness: at least one harness must be provi
• Invalid argument for parameter output: Invalid output type.
• Continuation maxAgeMs must be a positive integer.

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