vercel/ai · error · Error

ACP lifecycle state data is missing.

Error message

ACP lifecycle state data is missing.

What it means

When the v1 harness starts in resume mode (isResume), it expects serialized lifecycle state from a previous run to be present. If lifecycleData is null/undefined the harness cannot restore the prior session and throws instead of silently starting fresh. This guards against resuming from missing or corrupted persisted state.

Source

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

      const onDiagnostic = report
        ? (frame: Parameters<typeof harnessV1DiagnosticFromBridgeFrame>[0]) =>
            report(
              harnessV1DiagnosticFromBridgeFrame(frame, {
                sessionId: startOptions.sessionId,
                timestamp: Date.now(),
              }),
            )
        : undefined;
      const onBridgeError = createBridgeErrorHandler({
        harnessId: settings.harnessId,
        sessionId: startOptions.sessionId,
      });
      const builtinToolCatalog = serializeBuiltinTools({ builtinTools });
      let respawnStrategy: ACPRespawnStrategy | undefined;

      if (isResume) {
        if (lifecycleData == null) {
          throw new Error('ACP lifecycle state data is missing.');
        }
        const coords = lifecycleData.bridge;
        if (coords == null && isContinue) {
          throw unsupported({
            harnessId: settings.harnessId,
            message:
              'ACP continuation state does not contain bridge coordinates required for replay or process-loss rerun.',
          });
        }
        if (coords != null) {
          try {
            const endpoint = await resolveBridgeEndpoint({
              sandboxSession,
              override: portEndpointOverride,
              port: coords.port,
              harnessId: settings.harnessId,
            });
            const attachEndpoint = withBridgeToken({

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Start a fresh session instead of resuming when no prior state exists.
2. Verify the lifecycle state store/path actually contains data for this harnessId before resuming.
3. Ensure the previous run completed persisting state (check for crashes mid-write).
4. Pass the correct lifecycleData payload into the harness if you supply it programmatically.

Example fix

// before
harness.resume({ sessionId }); // throws: lifecycle state missing
// after
const state = await loadLifecycleState(sessionId);
if (state == null) {
  await harness.start(); // fresh session
} else {
  await harness.resume({ sessionId });
}

const state = await loadLifecycleState(sessionId);
if (state == null) {
  // no prior state: start fresh instead of resuming
  await harness.start();
} else {
  await harness.resume({ sessionId });
}

function hasLifecycleState(s: unknown): s is NonNullable<typeof s> {
  return s != null && typeof s === 'object' && 'bridge' in (s as object);
}

try {
  await harness.resume({ sessionId });
} catch (error) {
  if (error instanceof Error && error.message === 'ACP lifecycle state data is missing.') {
    await harness.start(); // fall back to a fresh session
  } else {
    throw error;
  }
}

When it happens

Trigger: Starting the harness with a resume/continue configuration while the lifecycle state blob passed in (or loaded from disk) is null — e.g. the state file was deleted, the wrong storage key was read, or resume was requested on a first run that never persisted state.

Common situations: Pointing resume at a fresh container/volume where prior state never existed; a failed previous run that crashed before persisting state; key collisions or env-specific state paths; manually clearing state directories then resuming.

Related errors

• Invalid argument for parameter requests: requests must not b
• Invalid argument for parameter requests: request IDs must no
• Invalid argument for parameter requests: request IDs must be
• Invalid argument for parameter batch: batch must be a suppor
• The persisted ACP turn start configuration is incompatible w

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