{"record":{"id":"51e64c16007a0816","repo":"paperclipai/paperclip","slug":"native-session-recovery-failed","errorCode":"native_session_recovery_failed","errorMessage":"native_session_recovery_failed: ${recovery.reason ?? \"unknown\"}","messagePattern":"native_session_recovery_failed: (.+?)","errorType":"error_code","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/native-session-runtime.ts","lineNumber":1883,"sourceCode":"                signal,\n              }),\n            onLateResolution: async (lateRecovery) => {\n              if (lateRecovery.session) {\n                await disposeUnadmittedSession(\n                  lateRecovery.session,\n                  \"native session provider recovery timed out\",\n                  cleanupDomain,\n                );\n              }\n            },\n          })\n        : {\n            recovered: false as const,\n            reason: \"driver does not support recovery\",\n          };\n    if (!recovery.recovered || !recovery.session) {\n      if (!replacementAllowed) {\n        throw new Error(\n          `native_session_recovery_failed: ${recovery.reason ?? \"unknown\"}`,\n        );\n      }\n      continuityBreak = {\n        reason: recovery.reason ?? \"provider session is no longer recoverable\",\n        previousDriverSessionId: providerRecoveryCheckpoint.sessionId,\n        previousProviderSessionId:\n          providerRecoveryCheckpoint.providerSessionId ?? null,\n      };\n      const replacementInput = {\n        identity,\n        workingDirectory: input.workspace.cwd,\n      };\n      session = await runAbortableOperationWithin({\n        timeoutMs: recoveryTimeoutMs,\n        timeoutMessage: `native session replacement bootstrap timed out after ${recoveryTimeoutMs}ms`,\n        operation: (signal) => {\n          const abortableReplacementInput = { ...replacementInput, signal };","sourceCodeStart":1865,"sourceCodeEnd":1901,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/native-session-runtime.ts#L1865-L1901","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the embedded recovery.reason in the message to see why the provider rejected recovery","Allow a replacement session (enable the replacement/continuity-break option) so the run can continue with a new session","Start a fresh session instead of resuming the stale checkpoint","Upgrade the driver/adapter to a version that supports session recovery"],"exampleFix":"// before\nrun({ resumeCheckpoint: cp, allowReplacement: false });\n// after\ntry {\n  run({ resumeCheckpoint: cp, allowReplacement: false });\n} catch (e) {\n  if (String(e.message).startsWith('native_session_recovery_failed')) {\n    run({ allowReplacement: true }); // continue with a new session\n  }\n}","handlingStrategy":"fallback","validationCode":"// check checkpoint freshness / driver support before resuming\nif (!driver.supportsRecovery || isStale(checkpoint)) startFreshSession();","typeGuard":null,"tryCatchPattern":"try { resume(cp) } catch (e) { if (String(e.message).startsWith('native_session_recovery_failed')) startFreshSession(); else throw e; }","preventionTips":["Always enable replacement/continuity-break for long-running runs","Persist and check checkpoint timestamps; skip recovery for very old checkpoints","Verify driver recovery support before relying on resume","Monitor recovery.reason values to detect provider-side expiry patterns"],"tags":["session","recovery","provider"],"backgroundTag":"invalid-state-transition","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}