{"record":{"id":"e824840a49535311","repo":"vercel/ai","slug":"the-claude-code-harness-cannot-use-mintbridgetoke","errorCode":null,"errorMessage":"The Claude Code harness cannot use `mintBridgeToken` with a sandbox session that does not expose an id.","messagePattern":"The Claude Code harness cannot use `mintBridgeToken` with a sandbox session that does not expose an id\\.","errorType":"exception","errorClass":"HarnessCapabilityUnsupportedError","httpStatus":null,"severity":"error","filePath":"packages/harness-claude-code/src/claude-code-harness.ts","lineNumber":855,"sourceCode":"    specificationVersion: 'harness-v1',\n    harnessId: 'claude-code',\n    builtinTools: CLAUDE_CODE_BUILTIN_TOOLS,\n    supportsBuiltinToolApprovals: true,\n    supportsBuiltinToolFiltering: true,\n    lifecycleStateSchema: claudeCodeResumeStateSchema,\n    getBootstrap: getClaudeCodeBootstrap,\n    doStart: async startOpts => {\n      const sandboxSession = startOpts.sandboxSession;\n      const toolSafeSandboxSession =\n        getRestrictedSandboxSession(sandboxSession);\n      const sandboxId = 'id' in sandboxSession ? sandboxSession.id : undefined;\n      validateBasicSandboxSettings({\n        sandboxSession,\n        port: settings.port,\n        portEndpoint: settings.portEndpoint,\n      });\n      if (settings.mintBridgeToken != null && sandboxId == null) {\n        throw new HarnessCapabilityUnsupportedError({\n          harnessId: 'claude-code',\n          message:\n            'The Claude Code harness cannot use `mintBridgeToken` with a sandbox session that does not expose an id.',\n        });\n      }\n      const defaultWorkingDirectory =\n        await resolveSandboxDefaultWorkingDirectory({\n          sandboxSession,\n          abortSignal: startOpts.abortSignal,\n        });\n      const lifecycleState = startOpts.continueFrom ?? startOpts.resumeFrom;\n      const isResume = lifecycleState != null;\n      const isContinue = startOpts.continueFrom != null;\n      const resumeData = isResume\n        ? (lifecycleState?.data as {\n            bridge?: ClaudeCodeBridgeCoords;\n            sandboxCredentialEnvironment?: Record<string, string>;\n            claudeSessionId?: string;","sourceCodeStart":837,"sourceCodeEnd":873,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-claude-code/src/claude-code-harness.ts#L837-L873","documentation":"When a Claude Code session runs inside a sandbox, `mintBridgeToken` requires the sandbox session to expose an `id`, because the minted bridge token is bound to that session id. If `mintBridgeToken` is set but the resolved `sandboxId` is null/undefined, `createClaudeCode` throws `HarnessCapabilityUnsupportedError` (harnessId `claude-code`).","triggerScenarios":"`createClaudeCode({ sandboxSession, mintBridgeToken: true })` (or a mint function) where the sandbox session's id is null — i.e. a sandbox session created without an id or a session type that does not expose one — while the basic-sandbox checks in `validateBasicSandboxSettings` already passed.","commonSituations":"Connecting to a pre-existing/basic sandbox session that was created without requesting an id; upgrading the harness and newly enabling `mintBridgeToken` on an old session object; a sandbox provider returning a session without an id field.","solutions":["Recreate the sandbox session so it exposes a non-null `id` (request an id when creating the session), then pass it with `mintBridgeToken`.","Drop the `mintBridgeToken` option if bridge-token minting is not required for this session.","Use a sandbox session type/provider that supports ids (e.g. a network sandbox session exposing `getPortEndpoint`/id) instead of a basic session.","Check `sandboxSession.id` (or your provider's id accessor) before enabling `mintBridgeToken` and fail early with a clear message."],"exampleFix":"// before\nconst session = await createBasicSandbox({ withId: false });\ncreateClaudeCode({ sandboxSession: session, mintBridgeToken: true });\n// after\nconst session = await createBasicSandbox({ withId: true });\ncreateClaudeCode({ sandboxSession: session, mintBridgeToken: session.id != null });","handlingStrategy":"validation","validationCode":"function assertMintBridgeTokenSupported(sandboxSession, settings) {\n  if (settings.mintBridgeToken != null && (sandboxSession.id == null)) {\n    throw new TypeError('mintBridgeToken requires a sandbox session with a non-null id');\n  }\n}\nassertMintBridgeTokenSupported(sandboxSession, settings);","typeGuard":"function sandboxExposesId(session) {\n  return typeof session === 'object' && session !== null && 'id' in session && session.id != null;\n}","tryCatchPattern":"import { HarnessCapabilityUnsupportedError } from '@ai-sdk/harness';\ntry {\n  return createClaudeCode(settings);\n} catch (err) {\n  if (HarnessCapabilityUnsupportedError.isInstance?.(err) || err?.name === 'HarnessCapabilityUnsupportedError') {\n    if (err.message.includes('mintBridgeToken')) {\n      return createClaudeCode({ ...settings, mintBridgeToken: undefined });\n    }\n  }\n  throw err;\n}","preventionTips":["Only enable mintBridgeToken for sandbox sessions created with an id","Check session.id != null before passing mintBridgeToken","Prefer network sandbox sessions that expose ids/endpoints for token workflows"],"tags":["sandbox","configuration","capability-unsupported","harness-claude-code"],"backgroundTag":"sandbox-session-missing-id","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}