vercel/ai · warning

HarnessAgent: `onSandboxSession` is deprecated. Use `sandbox

Error message

HarnessAgent: `onSandboxSession` is deprecated. Use `sandboxConfig.onSession` instead.

What it means

HarnessAgent prints a deprecation warning when `onSandboxSession` is set in settings: that option has moved to `sandboxConfig.onSession`. The warning is emitted by resolveSandboxConfig while still honoring the old option (spreading it into the resolved config).

Source

Thrown at packages/harness/src/agent/harness-agent.ts:1157

  get request() {
    return this.finalStep.request;
  }

  get response() {
    return this.finalStep.response;
  }

  get providerMetadata() {
    return this.finalStep.providerMetadata;
  }
}

function resolveSandboxConfig(
  settings: Pick<HarnessAgentSettings, 'sandboxConfig' | 'onSandboxSession'>,
): HarnessAgentSandboxConfig {
  if (settings.onSandboxSession != null) {
    console.warn(
      'HarnessAgent: `onSandboxSession` is deprecated. Use `sandboxConfig.onSession` instead.',
    );
  }

  return {
    ...settings.sandboxConfig,
    ...(settings.sandboxConfig?.onSession == null &&
    settings.onSandboxSession != null
      ? { onSession: settings.onSandboxSession }
      : {}),
  };
}

async function cleanupAfterStartFailure(input: {
  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
  ownsSandboxLifecycle: boolean;
}): Promise<void> {
  if (!input.ownsSandboxLifecycle) return;

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Move the callback into settings.sandboxConfig.onSession
2. Remove the top-level onSandboxSession property
3. Silence the warning by completing the migration before the option is removed

Example fix

// before
new HarnessAgent({ onSandboxSession: session => {...} });
// after
new HarnessAgent({
  sandboxConfig: { onSession: session => {...} },
});

if ('onSandboxSession' in settings) {
  console.warn('onSandboxSession is deprecated; use sandboxConfig.onSession');
}

When it happens

Trigger: Constructing/configuring HarnessAgent with a top-level `onSandboxSession` callback in HarnessAgentSettings; the code warns and maps it into sandboxConfig.

Common situations: Upgrading across harness versions where the sandbox callback moved; copied older example code; TypeScript may still accept the deprecated field during the migration window.

Related errors

• 'HarnessAgent: `sandboxConfig.onBootstrap` and `sandboxConfi
• Failed to resolve sandbox default working directory (exit ${
• Failed to resolve sandbox default working directory: expecte
• Unable to resolve sandbox HOME directory: ${result.stderr ||
• Invalid AI SDK harness skills manifest: ${manifestPath}

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