{"record":{"id":"67ca750e12a7d566","repo":"vercel/ai","slug":"the-codex-harness-requires-an-explicit-port-when","errorCode":null,"errorMessage":"The codex harness requires an explicit `port` when using a basic sandbox session.","messagePattern":"The codex harness requires an explicit `port` when using a basic sandbox session\\.","errorType":"exception","errorClass":"HarnessCapabilityUnsupportedError","httpStatus":null,"severity":"error","filePath":"packages/harness-codex/src/codex-harness.ts","lineNumber":591,"sourceCode":"    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) {\n    throw new HarnessCapabilityUnsupportedError({\n      harnessId: 'codex',\n      message:\n        'The codex harness requires an explicit `port` when using a basic sandbox session.',\n    });\n  }\n  if (portEndpoint == null) {\n    throw new HarnessCapabilityUnsupportedError({\n      harnessId: 'codex',\n      message:\n        'The codex harness requires an explicit `portEndpoint` when using a basic sandbox session.',\n    });\n  }\n}\n\nasync function resolveBridgeEndpoint({\n  sandboxSession,\n  override,\n  port,","sourceCodeStart":573,"sourceCodeEnd":609,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-codex/src/codex-harness.ts#L573-L609","documentation":"validateBasicSandboxSettings checks settings for 'basic' sandbox sessions (those without getPortEndpoint). Such sessions cannot derive an endpoint, so the harness demands an explicit `port`; if port is null it throws HarnessCapabilityUnsupportedError. (A following check similarly requires portEndpoint.)","triggerScenarios":"createCodex with a sandboxSession lacking getPortEndpoint and neither `port` nor (later) `portEndpoint` provided in settings.","commonSituations":"Using a basic sandbox session type but forgetting createCodex({ port }); code that worked with a full sandbox session (with getPortEndpoint) reused with a basic session.","solutions":["Pass an explicit port: createCodex({ port: 4096, sandboxSession }).","Also provide portEndpoint if required by the following validation step.","Use a sandbox session implementing getPortEndpoint so the port can be resolved automatically."],"exampleFix":"// before\ncreateCodex({ sandboxSession: basicSession }); // basic session, no port\n// after\ncreateCodex({ sandboxSession: basicSession, port: 4096, portEndpoint: 'sandbox.example.com:4096' });","handlingStrategy":"validation","validationCode":"if (!('getPortEndpoint' in sandboxSession) && (settings.port == null || settings.portEndpoint == null)) {\n  throw new Error('basic sandbox sessions require explicit port and portEndpoint');\n}","typeGuard":"function isFullSandboxSession(s) {\n  return typeof s === 'object' && s !== null && 'getPortEndpoint' in s;\n}","tryCatchPattern":"try {\n  const codex = createCodex(settings);\n} catch (e) {\n  if (/requires an explicit `port`/.test(String(e?.message))) {\n    // add port (and portEndpoint) to settings and rebuild\n  } else throw e;\n}","preventionTips":["Provide port and portEndpoint whenever using a basic sandbox session","Prefer full sandbox sessions implementing getPortEndpoint","Validate sandbox settings at construction time, not at start"],"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"}