{"record":{"id":"2585132394d622ea","repo":"paperclipai/paperclip","slug":"native-runner-warm-transition-requires-exact-owned","errorCode":null,"errorMessage":"native_runner_warm_transition_requires_exact_owned_endpoint","messagePattern":"native_runner_warm_transition_requires_exact_owned_endpoint","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/live/runnerd-codex-transport.ts","lineNumber":4656,"sourceCode":"      controlPlaneState?.schema ===\n        \"paperclip.runner.durable.control-plane-state.warm-transition.v1\" ||\n      hasRunnerWarmBoundary ||\n      candidateRunnerState?.warmTransition !== undefined ||\n      candidateRunnerState?.schema ===\n        \"paperclip.runner.durable.state.warm-transition.v1\";\n    if (hasWarmBoundary) {\n      // This lane must precede ordinary archive/identity-rebinding recovery.\n      // No malformed or unsupported transition is reinterpreted as legacy.\n      if (\n        (!localStateOwner && !this.options.readRunnerState) ||\n        !localProvider ||\n        !controlPlaneState ||\n        !candidateRunnerState ||\n        (this.options.controlPlaneRegistration !== undefined &&\n          this.options.warmTransitionRegistrationMode !== \"routed_connect\") ||\n        this.options.adoptExistingRunner !== undefined\n      ) {\n        throw new Error(\n          \"native_runner_warm_transition_requires_exact_owned_endpoint\",\n        );\n      }\n      const artifact = approvedRunnerArtifact(\n        this.options.runnerBinary ?? defaultCapabilityRunnerdBinary(),\n      );\n      const proof = inspectWarmRunTransition({\n        controlPlaneState,\n        runnerState: candidateRunnerState,\n        expectedNewIdentity: desiredIdentity,\n        expectedRunnerVersion: artifact.version,\n        expectedRunnerDigest: artifact.digest,\n      });\n      if (!proof)\n        throw new Error(\"native_runner_warm_transition_snapshot_mismatch\");\n      const receipt = proof.receipt;\n      const connection = receipt.connection;\n      const endpoint =","sourceCodeStart":4638,"sourceCodeEnd":4674,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/live/runnerd-codex-transport.ts#L4638-L4674","documentation":"Thrown when a native runner warm transition is requested but the transport options do not exactly describe an owned, routed-connect endpoint. A warm transition requires: control-plane state, a candidate runner state, controlPlaneRegistration set with warmTransitionRegistrationMode === \"routed_connect\", and no adoptExistingRunner option. Anything else is rejected to prevent hijacking or misdirecting a warm handover.","triggerScenarios":"Calling the warm-transition path with: missing controlPlaneState or candidate runner state; controlPlaneRegistration defined while warmTransitionRegistrationMode is not \"routed_connect\"; or adoptExistingRunner set alongside a warm transition.","commonSituations":"Mixing adoption options (adoptExistingRunner) with warm-transition options in a shared config object; forgetting to set warmTransitionRegistrationMode after enabling controlPlaneRegistration; upgrading a runner where registration mode defaults changed.","solutions":["Set warmTransitionRegistrationMode to \"routed_connect\" when controlPlaneRegistration is provided","Remove adoptExistingRunner from options when performing a warm transition","Ensure both controlPlaneRegistration and candidate runner state are present before requesting the warm transition","Use the adoption path instead if you intend to attach to an existing runner, not a warm transition"],"exampleFix":"// before\nconst options = { controlPlaneRegistration, warmTransitionRegistrationMode: \"adopt\", adoptExistingRunner: true };\n// after\nconst options = { controlPlaneRegistration, warmTransitionRegistrationMode: \"routed_connect\" };","handlingStrategy":"validation","validationCode":"const warmReady =\n  options.controlPlaneRegistration !== undefined &&\n  options.warmTransitionRegistrationMode === \"routed_connect\" &&\n  options.adoptExistingRunner === undefined;\nif (!warmReady) throw new Error(\"options do not satisfy warm-transition requirements\");","typeGuard":"null","tryCatchPattern":"try {\n  await transport.beginWarmTransition();\n} catch (err) {\n  if (err instanceof Error && err.message === \"native_runner_warm_transition_requires_exact_owned_endpoint\") {\n    // fix option combination, then retry\n  } else throw err;\n}","preventionTips":["Keep warm-transition options and adoption options in separate config branches","Assert warmTransitionRegistrationMode === \"routed_connect\" wherever controlPlaneRegistration is set","Document that adoptExistingRunner and warm transitions are mutually exclusive"],"tags":["warm-transition","configuration","registration"],"backgroundTag":"conflicting-config-options","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}