vercel/ai · error · HarnessCapabilityUnsupportedError

The deepagents harness needs a TCP port exposed by the sandb

Error message

The deepagents harness needs a TCP port exposed by the sandbox. Create the sandbox with `ports: [<port>]` or pass `createDeepAgents({ port })`.

What it means

The deepagents bridge runs over TCP, so its port must come from either an explicit `port` override or the first entry of the sandbox session's exposed `ports` list. `resolveBridgePort` throws `HarnessCapabilityUnsupportedError` when neither is available, since there is no endpoint to reach the in-sandbox bridge process.

Source

Thrown at packages/harness-deepagents/src/deepagents-harness.ts:503

        recursionLimit: settings.recursionLimit,
        mcpServers: settings.mcpServers,
      });
    },
  };
}

function resolveBridgePort({
  sandboxSession,
  override,
}: {
  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
  override: number | undefined;
}): number {
  if (override !== undefined) return override;
  if ('ports' in sandboxSession && sandboxSession.ports.length > 0) {
    return sandboxSession.ports[0];
  }
  throw new HarnessCapabilityUnsupportedError({
    harnessId: 'deepagents',
    message:
      'The deepagents harness needs a TCP port exposed by the sandbox. ' +
      'Create the sandbox with `ports: [<port>]` or pass `createDeepAgents({ port })`.',
  });
}

function validateBasicSandboxSettings({
  sandboxSession,
  port,
  portEndpoint,
}: {
  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
  port: number | undefined;
  portEndpoint: HarnessV1PortEndpoint | undefined;
}): void {
  if ('getPortEndpoint' in sandboxSession) return;
  if (port == null) {

View on GitHub (pinned to 69428b1f8b)

Solutions

Create the sandbox with a forwarded port: e.g. `ports: [8080]` in the sandbox options.
Pass the port explicitly: `createDeepAgents({ port: 8080 })`, matching the port forwarded in the sandbox.
Verify with your sandbox provider that port forwarding is supported and the `ports` array is populated on the session.
Check the sandbox provider SDK version — ensure the session object actually reports exposed ports.

Example fix

// before
createDeepAgents({}) // sandbox without ports
// after
createDeepAgents({ port: 8080 }) // sandbox created with ports: [8080]

Defensive patterns

Strategy: validation

Validate before calling

const hasPort =
  settings.port !== undefined ||
  ('ports' in sandboxSession && sandboxSession.ports.length > 0);
if (!hasPort) {
  throw new Error('Create the sandbox with ports: [<port>] or pass createDeepAgents({ port })');
}

Type guard

function exposesPorts(s: object): s is { ports: number[] } {
  return 'ports' in s && Array.isArray((s as { ports?: unknown }).ports) && (s as { ports: unknown[] }).ports.length > 0;
}

Try / catch

try {
  await harness.start(opts);
} catch (error) {
  if (error instanceof HarnessCapabilityUnsupportedError && error.message.includes('TCP port')) {
    // recreate the sandbox with forwarded ports or set the `port` option
  }
  throw error;
}

Prevention

Always create the sandbox with a forwarded port for deepagents
Pass `createDeepAgents({ port })` explicitly as a default
Verify the provider populates `session.ports` after creation
Confirm your sandbox backend supports port forwarding

When it happens

Trigger: Starting the deepagents harness with a sandbox session whose `ports` array is empty or absent, and without passing `createDeepAgents({ port })` (or the per-call port override).

Common situations: Creating the sandbox without port forwarding options; a sandbox provider that doesn't support port exposure; forgetting the `port` setting after switching to a sandbox backend that doesn't auto-forward; a provider SDK returning `ports: []` because forwarding failed silently.

Related errors

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