{"record":{"id":"063eba9c9dffee2c","repo":"vercel/ai","slug":"the-claude-code-harness-requires-an-explicit-port","errorCode":null,"errorMessage":"The Claude Code harness requires an explicit `port` when using a basic sandbox session.","messagePattern":"The Claude Code harness requires an explicit `port` when using a basic sandbox session\\.","errorType":"exception","errorClass":"HarnessCapabilityUnsupportedError","httpStatus":null,"severity":"error","filePath":"packages/harness-claude-code/src/claude-code-harness.ts","lineNumber":1223,"sourceCode":"    harnessId: 'claude-code',\n    message:\n      'The claude-code harness needs a TCP port exposed by the sandbox. ' +\n      'Create the sandbox with `ports: [<port>]` or pass `createClaudeCode({ 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: 'claude-code',\n      message:\n        'The Claude Code harness requires an explicit `port` when using a basic sandbox session.',\n    });\n  }\n  if (portEndpoint == null) {\n    throw new HarnessCapabilityUnsupportedError({\n      harnessId: 'claude-code',\n      message:\n        'The Claude Code 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":1205,"sourceCodeEnd":1241,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-claude-code/src/claude-code-harness.ts#L1205-L1241","documentation":"For a 'basic' sandbox session — one that does not implement `getPortEndpoint` — the Claude Code harness cannot discover ports on its own, so an explicit `port` in `createClaudeCode` settings is mandatory. `validateBasicSandboxSettings` throws `HarnessCapabilityUnsupportedError` (harnessId `claude-code`) when the session lacks `getPortEndpoint` and `port` is null/undefined.","triggerScenarios":"`createClaudeCode({ sandboxSession, port: undefined })` where `sandboxSession` has no `getPortEndpoint` method (i.e. a `SandboxSession` rather than a `HarnessV1NetworkSandboxSession`).","commonSituations":"Using a plain/basic sandbox from a provider that does not implement the network-session interface; removing the `port` option during a refactor while still on a basic session; assuming port auto-discovery works for all session types (it only works with `getPortEndpoint` or a `ports`-bearing session).","solutions":["Pass an explicit `port` in `createClaudeCode` settings, e.g. `createClaudeCode({ sandboxSession, port: 3000 })`.","Switch to a `HarnessV1NetworkSandboxSession` that implements `getPortEndpoint` so the harness can resolve the port itself.","If the session does expose `ports`, note that `resolveBridgePort` may cover the no-override case — but for sessions lacking `getPortEndpoint` the validator still demands an explicit `port`, so provide one.","Check the session type before configuring: `if (!('getPortEndpoint' in session)) ensure port is set`."],"exampleFix":"// before\ncreateClaudeCode({ sandboxSession: basicSession });\n// after\ncreateClaudeCode({ sandboxSession: basicSession, port: 3000 });","handlingStrategy":"validation","validationCode":"function assertBasicSandboxHasPort(sandboxSession, port) {\n  if ('getPortEndpoint' in sandboxSession) return; // network session: fine\n  if (port == null) {\n    throw new TypeError('Basic sandbox sessions require an explicit createClaudeCode({ port })');\n  }\n}\nassertBasicSandboxHasPort(sandboxSession, settings.port);","typeGuard":"function isNetworkSandboxSession(session) {\n  return typeof session === 'object' && session !== null && 'getPortEndpoint' in session;\n}","tryCatchPattern":"try {\n  return createClaudeCode({ sandboxSession, port, ...settings });\n} catch (err) {\n  if (err?.name === 'HarnessCapabilityUnsupportedError' && err.message.includes('requires an explicit `port`')) {\n    throw new Error('Config error: add `port` to createClaudeCode for basic sandbox sessions', { cause: err });\n  }\n  throw err;\n}","preventionTips":["Detect session type with 'getPortEndpoint' in session before configuring","Always supply port in createClaudeCode when using basic (non-network) sandbox sessions","Migrate to network sandbox sessions (getPortEndpoint) to avoid manual port wiring"],"tags":["sandbox","configuration","port","capability-unsupported","harness-claude-code"],"backgroundTag":"sandbox-requires-explicit-port","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}