vercel/ai · error · HarnessCapabilityUnsupportedError

The deepagents harness cannot use `mintBridgeToken` with a s

Error message

The deepagents harness cannot use `mintBridgeToken` with a sandbox session that does not expose an id.

What it means

`mintBridgeToken` requires the sandbox session to expose an `id`, because bridge tokens are minted per sandbox identity for reattachment. When the configured `mintBridgeToken` function is present but the sandbox session object has no `id` property, `createDeepAgents` throws `HarnessCapabilityUnsupportedError` at start rather than failing later during token minting.

Source

Thrown at packages/harness-deepagents/src/deepagents-harness.ts:236

    harnessId: 'deepagents',
    builtinTools: DEEPAGENTS_BUILTIN_TOOLS,
    // Built-in tool approvals are gated in-bridge via DeepAgents' interruptOn (HITL) middleware.
    supportsBuiltinToolApprovals: true,
    lifecycleStateSchema: deepAgentsResumeStateSchema,
    getBootstrap: getDeepAgentsBootstrap,
    doStart: async startOpts => {
      const permissionMode = startOpts.permissionMode;
      const sandboxSession = startOpts.sandboxSession;
      const toolSafeSandboxSession =
        getRestrictedSandboxSession(sandboxSession);
      const sandboxId = 'id' in sandboxSession ? sandboxSession.id : undefined;
      validateBasicSandboxSettings({
        sandboxSession,
        port: settings.port,
        portEndpoint: settings.portEndpoint,
      });
      if (settings.mintBridgeToken != null && sandboxId == null) {
        throw new HarnessCapabilityUnsupportedError({
          harnessId: 'deepagents',
          message:
            'The deepagents harness cannot use `mintBridgeToken` with a sandbox session that does not expose an id.',
        });
      }
      const defaultWorkingDirectory =
        await resolveSandboxDefaultWorkingDirectory({
          sandboxSession,
          abortSignal: startOpts.abortSignal,
        });
      const lifecycleState = startOpts.continueFrom ?? startOpts.resumeFrom;
      const isResume = lifecycleState != null;
      const isContinue = startOpts.continueFrom != null;
      const resumeData =
        isResume && typeof lifecycleState?.data === 'object'
          ? (lifecycleState.data as {
              bridge?: DeepAgentsBridgeCoords;
              sandboxCredentialEnvironment?: Record<string, string>;

View on GitHub (pinned to 69428b1f8b)

Solutions

Use a sandbox session that exposes a stable `id` property (e.g. the provider's native session object).
Remove the `mintBridgeToken` option if your sandbox cannot provide an id and you don't need authenticated bridge reattachment.
Update the sandbox provider SDK if a newer version exposes session ids.
Wrap the session to supply an id if your infrastructure can derive one (only if it's stable across reattach).

Example fix

// before
createDeepAgents({ mintBridgeToken: mintToken }) // session without id
// after
const session = await createSandboxSession(); // ensure { id } is present
createDeepAgents({ mintBridgeToken: mintToken }) // or drop mintBridgeToken

Defensive patterns

Strategy: validation

Validate before calling

if (settings.mintBridgeToken != null && !('id' in sandboxSession)) {
  throw new Error('mintBridgeToken requires a sandbox session with an id');
}

Type guard

function hasSandboxId(s: object): s is { id: string } {
  return 'id' in s && typeof (s as { id?: unknown }).id === 'string';
}

Try / catch

try {
  await harness.start(opts);
} catch (error) {
  if (error instanceof HarnessCapabilityUnsupportedError && error.message.includes('mintBridgeToken')) {
    // drop mintBridgeToken or switch to an id-bearing sandbox session
  }
  throw error;
}

Prevention

Use sandbox providers whose sessions expose a stable `id`
Only set mintBridgeToken when the session type includes `id`
Type your sandbox session as having `{ id: string }` when using token minting

When it happens

Trigger: Calling `createDeepAgents({ mintBridgeToken: fn })` and starting the harness with a `sandboxSession` object that lacks an `id` field (custom or minimal sandbox session implementations).

Common situations: Using a custom sandbox provider that doesn't surface session ids; constructing a sandbox session manually for tests without an `id`; a provider SDK version whose session type dropped or renamed `id`.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/f5901cc223fb8e25. Report an issue: GitHub.