{"record":{"id":"aff82c6f765856e3","repo":"paperclipai/paperclip","slug":"native-session-multi-run-unavailable-aff82c","errorCode":"native_session_multi_run_unavailable","errorMessage":"native_session_multi_run_unavailable","messagePattern":"native_session_multi_run_unavailable","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/native-session-runtime.ts","lineNumber":1872,"sourceCode":"  const identity = {\n    runId: input.binding.runId,\n    sessionId: normalizedSessionId,\n    companyId: input.binding.companyId,\n    issueId: input.binding.issueId,\n    agentId: input.binding.agentId,\n  };\n  let recovered = false;\n  let session: NativeSession | null = null;\n  let continuityBreak: {\n    reason: string;\n    previousDriverSessionId: string;\n    previousProviderSessionId: string | null;\n  } | null = null;\n  let reconciledRecoveryCheckpoint: PersistedNativeSession | null = null;\n  await options.onSessionAdmission?.();\n  if (options.existingSession) {\n    if (options.existingSession.attachRun === undefined) {\n      throw new Error(\"native_session_multi_run_unavailable\");\n    }\n    // Attaching can fail even after the retained session's identity passes the\n    // static binding check (for example, when the provider lost multi-run\n    // state). Prove the provider attachment before opening durable\n    // control-plane state because ControlPlanePort has no rollback operation.\n    try {\n      await options.existingSession.attachRun({ identity });\n    } catch (error) {\n      // attachRun has no transactional guarantee: a provider may bind the new\n      // run before reporting a later failure. Conservatively quarantine the\n      // session so neither the old nor partially attached run can reuse it.\n      await quarantineRetainedSession(\n        options.existingSession,\n        options.onSession,\n        \"native session attachment failed\",\n        cleanupDomain,\n      );\n      throw error;","sourceCodeStart":1854,"sourceCodeEnd":1890,"githubUrl":"https://github.com/paperclipai/paperclip/blob/3f1d897a7c018d76563a21c6e39c3c9b03933622/packages/paperclip-runner/src/native-session-runtime.ts#L1854-L1890","documentation":"Thrown as a bare Error (code `native_session_multi_run_unavailable`) when a native session is being resumed via `options.existingSession` but that session object lacks an `attachRun` function. The runtime requires an attachRun capability to re-bind a retained provider session to a new run; without it, multi-run attachment of that session is unsupported and resume cannot proceed.","triggerScenarios":"Calling the native session runtime with `options.existingSession` set where `existingSession.attachRun === undefined` — i.e. a persisted/retained session produced by an older code path or provider adapter that never exposed attachRun.","commonSituations":"Resuming sessions created before the attachRun capability was introduced (version skew between persisted state and current runtime); using a provider adapter that does not support multi-run session attachment; a hand-constructed or partially hydrated PersistedNativeSession missing the attach callback.","solutions":["Recreate the session instead of resuming: drop existingSession and start a fresh native session run","Ensure the code path producing the persisted session supplies attachRun (upgrade the adapter/runtime that created it)","Verify the provider actually supports multi-run attachment before attempting to attach a retained sessionId","Check for version mismatch between where the session was persisted and the current runner version"],"exampleFix":"// before\nawait startNativeSession({ existingSession: persistedSession }); // attachRun undefined\n// after\nif (typeof persistedSession.attachRun !== \"function\") {\n  await startNativeSession({}); // fresh session\n} else {\n  await startNativeSession({ existingSession: persistedSession });\n}","handlingStrategy":"type-guard","validationCode":"if (options.existingSession && typeof options.existingSession.attachRun !== \"function\") {\n  throw new Error(\"Retained session lacks attachRun; start a fresh session instead\");\n}","typeGuard":"function supportsMultiRunAttach(s) {\n  return !!s && typeof s.attachRun === \"function\";\n}","tryCatchPattern":"try {\n  await runtime.start({ existingSession: session });\n} catch (e) {\n  if (e.message === \"native_session_multi_run_unavailable\") {\n    await runtime.start({}); // fall back to a fresh session\n  } else throw e;\n}","preventionTips":["Check attachRun exists before passing existingSession","Upgrade/align the runtime version that persisted the session with the one resuming it","Confirm provider multi-run support before retaining sessions for reuse","Persist only sessions produced by attachRun-capable code paths"],"tags":["sessions","resume","compatibility","native-runtime"],"backgroundTag":"unsupported-operation","analyzedSha":"3f1d897a7c018d76563a21c6e39c3c9b03933622","analyzedAt":"2026-09-18T08:03:59.046Z","contentChangedAt":"2026-09-18T08:03:59.046Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}