vercel/ai · error · Error

The persisted ACP turn start configuration is incompatible w

Error message

The persisted ACP turn start configuration is incompatible with the current non-secret start configuration.

What it means

When a persisted ACP turn start configuration is loaded (e.g. during recovery/resume), validateACPTurnStartConfig recomputes a fingerprint from the persisted non-secret fields using the CURRENT runtime configuration (builtin tools, permission-mode mapping, model mapping, auth profile identity, session meta, etc.) and compares it to the persisted fingerprint. A mismatch means the runtime configuration changed since the state was persisted, so replaying the turn could behave differently than the original, and the harness refuses.

Source

Thrown at packages/harness-acp/src/v1/acp-v1-harness.ts:1786

    tools: turnStartConfig.tools,
    builtinTools,
    permissionMode: turnStartConfig.permissionMode,
    permissionModeMapping,
    mcpServers,
    debug: turnStartConfig.debug,
    authenticationProfile,
    sessionMeta,
    instructionMapping,
    responseFormat: turnStartConfig.responseFormat,
    outputSchemaMapping,
    model: turnStartConfig.model,
    modelMapping,
  });
  if (
    current.configurationFingerprint !==
    turnStartConfig.configurationFingerprint
  ) {
    throw new Error(
      'The persisted ACP turn start configuration is incompatible with the current non-secret start configuration.',
    );
  }
}

function validateACPColdSessionConfiguration({
  coldSession,
  permissionMode,
  authenticationProfile,
  sessionMeta,
  instructionMapping,
  outputSchemaMapping,
  modelMapping,
  builtinTools,
  permissionModeMapping,
  mcpServers,
  debug,
}: {

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Restore the same runtime configuration (builtin tools, mappings, auth profile, session meta, model mapping) that was active when the state was persisted.
2. Start a fresh session and replay the conversation history instead of resuming the incompatible persisted turn.
3. Check configuration fingerprints on lifecycle data before resuming and branch to a fresh session on mismatch.
4. Avoid upgrading the harness/agent version mid-session; resume persisted state with the same version that wrote it.

Example fix

// before
const session = await resumeACPV1({ lifecycleData }); // config changed since persist -> throws
// after
if (computeFingerprint(currentConfig) !== lifecycleData.turnStartConfig.configurationFingerprint) {
  session = await createACPV1({ /* fresh, matching config */ });
} else {
  session = await resumeACPV1({ lifecycleData });
}

function fingerprintsMatch(lifecycle, currentRuntime) {
  return lifecycle?.turnStartConfig?.configurationFingerprint ===
    computeTurnStartFingerprint(currentRuntime);
}
if (!fingerprintsMatch(lifecycleData, currentConfig)) { /* start fresh session */ }

try {
  session = await resumeACPV1({ lifecycleData });
} catch (e) {
  if (e instanceof Error && e.message.includes('incompatible with the current non-secret start configuration')) {
    session = await createACPV1({ /* matching fresh config */ });
  } else throw e;
}

When it happens

Trigger: Resuming/continuing a persisted turn after upgrading the harness or ACP implementation, changing builtinTools, model mapping, permission mode mapping, output schema mapping, authentication profile, sessionMeta, or mcpServers — any of which alters the recomputed configurationFingerprint.

Common situations: Deploying a new version of the harness/agent between persisting and resuming; editing provider tool catalogs or model IDs between runs; changing sessionMeta or auth profile across restarts; running the resume on a differently configured environment.

Related errors

• ACP cold-session state is incompatible with the current non-
• ACP process-loss rerun requires the agent to advertise sessi
• The ${model.provider} model "${model.modelId}" does not supp
• Invalid argument for parameter requests: requests must not b
• Invalid argument for parameter requests: request IDs must no

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