{"record":{"id":"0df21812b56a646c","repo":"vercel/ai","slug":"acp-authentication-and-session-profile-settings-ca","errorCode":null,"errorMessage":"ACP authentication and session profile settings cannot change after the ACP session has started.","messagePattern":"ACP authentication and session profile settings cannot change after the ACP session has started\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/harness-acp/src/v1/bridge/index.ts","lineNumber":385,"sourceCode":"  turn: BridgeTurn;\n}): Promise<{ initialHostToolCatalogRefreshRequired: boolean }> {\n  if (sessionConfigurationFailure != null) {\n    throw sessionConfigurationFailure.error;\n  }\n  const fingerprint = JSON.stringify({\n    authentication: bridgeConfiguration.authentication,\n    providerAuthentication: bridgeConfiguration.providerAuthentication,\n    providerEnvironment: bridgeConfiguration.providerEnvironment,\n    sessionMeta: bridgeConfiguration.sessionMeta,\n    instructionMapping: start.instructionMapping,\n    permissionMode: start.permissionMode,\n    permissionModeMapping: start.permissionModeMapping,\n    mcpServers: start.mcpServers,\n  });\n  if (session != null) {\n    if (catalogRefreshError != null) throw catalogRefreshError;\n    if (sessionConfigurationFingerprint !== fingerprint) {\n      throw new Error(\n        'ACP authentication and session profile settings cannot change after the ACP session has started.',\n      );\n    }\n    const relay = hostToolRelay;\n    if (relay == null) {\n      throw new Error('The host tool MCP relay is unavailable.');\n    }\n    try {\n      await refreshHostToolCatalog({\n        relay,\n        tools: start.tools ?? [],\n        harnessId: bridgeType,\n        timeoutMs: CATALOG_REFRESH_TIMEOUT_MS,\n      });\n    } catch (error) {\n      if (HarnessBridgeCapabilityUnsupportedError.isInstance(error)) {\n        catalogRefreshError = error;\n      }","sourceCodeStart":367,"sourceCodeEnd":403,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-acp/src/v1/bridge/index.ts#L367-L403","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nawait bridge.runTurn({ prompt, permissionModeMapping: 'yolo' });\nawait bridge.runTurn({ prompt, permissionModeMapping: 'default' }); // throws\n// after\nawait bridge.runTurn({ prompt, permissionModeMapping: 'default' });\nconst bridge2 = createBridge({ ..., permissionModeMapping: 'yolo' });\nawait bridge2.runTurn({ prompt });","handlingStrategy":"validation","validationCode":"type SessionProfile = { permissionModeMapping?: unknown; mcpServers?: unknown };\nfunction assertSameProfile(a: SessionProfile, b: SessionProfile): void {\n  if (JSON.stringify([a.permissionModeMapping, a.mcpServers]) !==\n      JSON.stringify([b.permissionModeMapping, b.mcpServers])) {\n    throw new Error('Auth/session profile changed; create a new bridge session');\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await bridge.runTurn({ prompt, ...startOptions });\n} catch (error) {\n  if (error instanceof Error && error.message.includes('cannot change after the ACP session has started')) {\n    // recreate the bridge/session with the new settings\n  }\n  throw error;\n}","preventionTips":["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."],"tags":["acp","session","configuration","immutability"],"backgroundTag":"session-config-immutable","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}