{"record":{"id":"bcad875d860c9cca","repo":"vercel/ai","slug":"the-deepagents-harness-needs-a-tcp-port-exposed-by","errorCode":null,"errorMessage":"The deepagents harness needs a TCP port exposed by the sandbox. Create the sandbox with `ports: [<port>]` or pass `createDeepAgents({ port })`.","messagePattern":"The deepagents harness needs a TCP port exposed by the sandbox\\. Create the sandbox with `ports: \\[<port>\\]` or pass `createDeepAgents\\((.+?)\\)`\\.","errorType":"exception","errorClass":"HarnessCapabilityUnsupportedError","httpStatus":null,"severity":"error","filePath":"packages/harness-deepagents/src/deepagents-harness.ts","lineNumber":503,"sourceCode":"        recursionLimit: settings.recursionLimit,\n        mcpServers: settings.mcpServers,\n      });\n    },\n  };\n}\n\nfunction resolveBridgePort({\n  sandboxSession,\n  override,\n}: {\n  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;\n  override: number | undefined;\n}): number {\n  if (override !== undefined) return override;\n  if ('ports' in sandboxSession && sandboxSession.ports.length > 0) {\n    return sandboxSession.ports[0];\n  }\n  throw new HarnessCapabilityUnsupportedError({\n    harnessId: 'deepagents',\n    message:\n      'The deepagents harness needs a TCP port exposed by the sandbox. ' +\n      'Create the sandbox with `ports: [<port>]` or pass `createDeepAgents({ port })`.',\n  });\n}\n\nfunction validateBasicSandboxSettings({\n  sandboxSession,\n  port,\n  portEndpoint,\n}: {\n  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;\n  port: number | undefined;\n  portEndpoint: HarnessV1PortEndpoint | undefined;\n}): void {\n  if ('getPortEndpoint' in sandboxSession) return;\n  if (port == null) {","sourceCodeStart":485,"sourceCodeEnd":521,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-deepagents/src/deepagents-harness.ts#L485-L521","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\ncreateDeepAgents({}) // sandbox without ports\n// after\ncreateDeepAgents({ port: 8080 }) // sandbox created with ports: [8080]","handlingStrategy":"validation","validationCode":"const hasPort =\n  settings.port !== undefined ||\n  ('ports' in sandboxSession && sandboxSession.ports.length > 0);\nif (!hasPort) {\n  throw new Error('Create the sandbox with ports: [<port>] or pass createDeepAgents({ port })');\n}","typeGuard":"function exposesPorts(s: object): s is { ports: number[] } {\n  return 'ports' in s && Array.isArray((s as { ports?: unknown }).ports) && (s as { ports: unknown[] }).ports.length > 0;\n}","tryCatchPattern":"try {\n  await harness.start(opts);\n} catch (error) {\n  if (error instanceof HarnessCapabilityUnsupportedError && error.message.includes('TCP port')) {\n    // recreate the sandbox with forwarded ports or set the `port` option\n  }\n  throw error;\n}","preventionTips":["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"],"tags":["sandbox","network","port","configuration"],"backgroundTag":"missing-port-configuration","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}