paperclipai/paperclip · error · Error

native_session_recovery_failed

native_session_recovery_failed

Error message

native_session_recovery_failed: ${recovery.reason ?? "unknown"}

What it means

Thrown by the native session runtime when a provider session could not be recovered from its recovery checkpoint and creating a replacement session is not allowed. Recovery fails when the driver does not support recovery or the provider reports the session is no longer recoverable, and the runtime refuses to silently break session continuity. The message embeds the driver-reported failure reason.

Source

Thrown at packages/paperclip-runner/src/native-session-runtime.ts:1883

                signal,
              }),
            onLateResolution: async (lateRecovery) => {
              if (lateRecovery.session) {
                await disposeUnadmittedSession(
                  lateRecovery.session,
                  "native session provider recovery timed out",
                  cleanupDomain,
                );
              }
            },
          })
        : {
            recovered: false as const,
            reason: "driver does not support recovery",
          };
    if (!recovery.recovered || !recovery.session) {
      if (!replacementAllowed) {
        throw new Error(
          `native_session_recovery_failed: ${recovery.reason ?? "unknown"}`,
        );
      }
      continuityBreak = {
        reason: recovery.reason ?? "provider session is no longer recoverable",
        previousDriverSessionId: providerRecoveryCheckpoint.sessionId,
        previousProviderSessionId:
          providerRecoveryCheckpoint.providerSessionId ?? null,
      };
      const replacementInput = {
        identity,
        workingDirectory: input.workspace.cwd,
      };
      session = await runAbortableOperationWithin({
        timeoutMs: recoveryTimeoutMs,
        timeoutMessage: `native session replacement bootstrap timed out after ${recoveryTimeoutMs}ms`,
        operation: (signal) => {
          const abortableReplacementInput = { ...replacementInput, signal };

View on GitHub (pinned to 01ad858492)

Solutions

1. Check the embedded recovery.reason in the message to see why the provider rejected recovery
2. Allow a replacement session (enable the replacement/continuity-break option) so the run can continue with a new session
3. Start a fresh session instead of resuming the stale checkpoint
4. Upgrade the driver/adapter to a version that supports session recovery

Example fix

// before
run({ resumeCheckpoint: cp, allowReplacement: false });
// after
try {
  run({ resumeCheckpoint: cp, allowReplacement: false });
} catch (e) {
  if (String(e.message).startsWith('native_session_recovery_failed')) {
    run({ allowReplacement: true }); // continue with a new session
  }
}

// check checkpoint freshness / driver support before resuming
if (!driver.supportsRecovery || isStale(checkpoint)) startFreshSession();

try { resume(cp) } catch (e) { if (String(e.message).startsWith('native_session_recovery_failed')) startFreshSession(); else throw e; }

When it happens

Trigger: Resuming a native agent session whose provider checkpoint cannot be restored (e.g. provider expired/invalidated the sessionId, or the driver lacks recovery support) while replacementAllowed is false.

Common situations: Long-lived sessions resumed after provider-side session expiry; using a driver/adapter version without recovery support; checkpoint referencing a session deleted server-side; operators running with continuity break disabled.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• OpenCode recovery failed
• provider turn ended with status ${turn.status}
• invalid_provider
• [paperclip] sandbox callback bridge kept queued request ${re
• [paperclip] sandbox callback bridge failed to abort queued r

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/51e64c16007a0816. Report an issue: GitHub.