ACP authentication and session profile settings cannot chang

Error message

ACP authentication and session profile settings cannot change after the ACP session has started.

What it means

ensureSession computes a configuration fingerprint from authentication and session profile settings (including permissionModeMapping and mcpServers). If a session already exists and the newly requested fingerprint differs from the one the session was created with, this Error is thrown because ACP does not allow re-authenticating or re-profiling an existing session. Callers must start a fresh session to change these settings.

Source

Thrown at packages/harness-acp/src/v1/bridge/index.ts:385

  turn: BridgeTurn;
}): Promise<{ initialHostToolCatalogRefreshRequired: boolean }> {
  if (sessionConfigurationFailure != null) {
    throw sessionConfigurationFailure.error;
  }
  const fingerprint = JSON.stringify({
    authentication: bridgeConfiguration.authentication,
    providerAuthentication: bridgeConfiguration.providerAuthentication,
    providerEnvironment: bridgeConfiguration.providerEnvironment,
    sessionMeta: bridgeConfiguration.sessionMeta,
    instructionMapping: start.instructionMapping,
    permissionMode: start.permissionMode,
    permissionModeMapping: start.permissionModeMapping,
    mcpServers: start.mcpServers,
  });
  if (session != null) {
    if (catalogRefreshError != null) throw catalogRefreshError;
    if (sessionConfigurationFingerprint !== fingerprint) {
      throw new Error(
        'ACP authentication and session profile settings cannot change after the ACP session has started.',
      );
    }
    const relay = hostToolRelay;
    if (relay == null) {
      throw new Error('The host tool MCP relay is unavailable.');
    }
    try {
      await refreshHostToolCatalog({
        relay,
        tools: start.tools ?? [],
        harnessId: bridgeType,
        timeoutMs: CATALOG_REFRESH_TIMEOUT_MS,
      });
    } catch (error) {
      if (HarnessBridgeCapabilityUnsupportedError.isInstance(error)) {
        catalogRefreshError = error;
      }

View on GitHub (pinned to 69428b1f8b)

Solutions

Keep authentication and session profile settings constant for the lifetime of a bridge/session; apply changes only before the first turn.
Create a new bridge/session instance when auth or permission-mode mapping must change.
Ensure environment-driven config (keys, mode mappings) cannot silently differ between calls for the same session.

Example fix

// before
await bridge.runTurn({ prompt, permissionModeMapping: 'yolo' });
await bridge.runTurn({ prompt, permissionModeMapping: 'default' }); // throws
// after
await bridge.runTurn({ prompt, permissionModeMapping: 'default' });
const bridge2 = createBridge({ ..., permissionModeMapping: 'yolo' });
await bridge2.runTurn({ prompt });

Defensive patterns

Strategy: validation

Validate before calling

type SessionProfile = { permissionModeMapping?: unknown; mcpServers?: unknown };
function assertSameProfile(a: SessionProfile, b: SessionProfile): void {
  if (JSON.stringify([a.permissionModeMapping, a.mcpServers]) !==
      JSON.stringify([b.permissionModeMapping, b.mcpServers])) {
    throw new Error('Auth/session profile changed; create a new bridge session');
  }
}

Try / catch

try {
  await bridge.runTurn({ prompt, ...startOptions });
} catch (error) {
  if (error instanceof Error && error.message.includes('cannot change after the ACP session has started')) {
    // recreate the bridge/session with the new settings
  }
  throw error;
}

Prevention

Freeze auth and permission-mode settings for the lifetime of a bridge instance.
Create a new bridge when authentication or permissionModeMapping must change.
Avoid hot-reloading config that mutates session-profile options between turns.

When it happens

Trigger: Calling a bridge/runTurn entry point again with changed authentication or session-profile options (e.g. different permissionModeMapping, auth method, or profile settings) while the previous ACP session is still cached in ensureSession.

Common situations: Reusing one harness bridge instance across turns but swapping permission modes or credentials between turns; hot-reloading config that alters auth options mid-session; passing per-request overrides that belong at session creation time.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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