{"record":{"id":"5d160864860d3b41","repo":"vercel/ai","slug":"the-codex-harness-needs-a-tcp-port-exposed-by-the","errorCode":null,"errorMessage":"The codex harness needs a TCP port exposed by the sandbox. Create the sandbox with `ports: [<port>]` or pass `createCodex({ port })`.","messagePattern":"The codex harness needs a TCP port exposed by the sandbox\\. Create the sandbox with `ports: \\[<port>\\]` or pass `createCodex\\((.+?)\\)`\\.","errorType":"exception","errorClass":"HarnessCapabilityUnsupportedError","httpStatus":null,"severity":"error","filePath":"packages/harness-codex/src/codex-harness.ts","lineNumber":572,"sourceCode":"        sandboxHomeDir,\n        turnConfigurationFingerprint,\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: 'codex',\n    message:\n      'The codex harness needs a TCP port exposed by the sandbox. ' +\n      'Create the sandbox with `ports: [<port>]` or pass `createCodex({ 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":554,"sourceCodeEnd":590,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-codex/src/codex-harness.ts#L554-L590","documentation":"resolveBridgePort determines the TCP port the Codex bridge listens on inside the sandbox. It uses an explicit override, otherwise the first port in sandboxSession.ports; if neither exists it throws HarnessCapabilityUnsupportedError because the harness has no way to reach the bridge.","triggerScenarios":"Accessing the session port (resolveBridgePort) when no `port` override was passed to createCodex and the sandboxSession has no `ports` array (or it is empty).","commonSituations":"Creating a sandbox without declaring exposed ports; passing a port override to one code path but not the one that starts the session; switching sandbox providers whose session type lacks `ports`.","solutions":["Create the sandbox with a port exposed, e.g. sandbox with `ports: [4096]`.","Pass an explicit port via createCodex({ port: 4096 }).","Verify sandboxSession.ports is populated if using a custom session implementation."],"exampleFix":"// before\ncreateCodex({ sandboxSession }); // sandbox created without ports\n// after\ncreateCodex({ port: 4096, sandboxSession }); // or create sandbox with ports: [4096]","handlingStrategy":"validation","validationCode":"const hasPort = overridePort != null || (sandboxSession && 'ports' in sandboxSession && sandboxSession.ports?.length > 0);\nif (!hasPort) throw new Error('codex harness needs an exposed sandbox port');","typeGuard":"function exposesPorts(s) {\n  return typeof s === 'object' && s !== null && 'ports' in s && Array.isArray(s.ports) && s.ports.length > 0;\n}","tryCatchPattern":"try {\n  await harness.start({});\n} catch (e) {\n  if (/needs a TCP port exposed by the sandbox/.test(String(e?.message))) {\n    // recreate sandbox with ports or pass createCodex({ port })\n  } else throw e;\n}","preventionTips":["Always create sandboxes for codex with at least one exposed port","Pass an explicit createCodex({ port }) as a safe default","Document required ports in sandbox provisioning code"],"tags":["harness-codex","sandbox","networking","port"],"backgroundTag":"missing-port-configuration","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}