{"record":{"id":"f319a9e53557438a","repo":"paperclipai/paperclip","slug":"acpx-provider-runtime-executable-lease-is-invalid","errorCode":null,"errorMessage":"ACPX provider runtime executable lease is invalid","messagePattern":"ACPX provider runtime executable lease is invalid","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts","lineNumber":1372,"sourceCode":"          : DEPENDENCY_ANCESTOR_FD_START +\n            dependencyAncestors.length +\n            providerRuntimeExecutableCount;\n        const runtimeHandoff =\n          verifiedRuntimeExecutableHandoff(runtimeTargetFd);\n        const environment = sanitizedNodeEnvironment(options.env);\n        delete environment[ACPX_PRIVATE_SNAPSHOT_ENV];\n        if (privateSnapshot) environment[ACPX_PRIVATE_SNAPSHOT_ENV] = JSON.stringify(privateSnapshot.handoff);\n        if (runtimeHandoff.environmentValue === undefined) {\n          delete environment[VERIFIED_RUNTIME_EXECUTABLE_ENV];\n        } else {\n          environment[VERIFIED_RUNTIME_EXECUTABLE_ENV] =\n            runtimeHandoff.environmentValue;\n        }\n        if (\n          (providerRuntimeExecutable === null) !==\n          (providerRuntimeEnvironmentVariable === null)\n        ) {\n          throw new Error(\"ACPX provider runtime executable lease is invalid\");\n        }\n        if (providerRuntimeEnvironmentVariable === null) {\n          delete environment[VERIFIED_PROVIDER_RUNTIME_TARGET_ENV];\n        } else {\n          environment[VERIFIED_PROVIDER_RUNTIME_TARGET_ENV] =\n            providerRuntimeEnvironmentVariable;\n        }\n        child = spawnChildProcess(\n          runtimeHandoff.executable,\n          guarded\n            ? [\n                // Keep resolved module URLs on the retained descriptor paths\n                // so the hook can distinguish them from host ancestry.\n                \"--preserve-symlinks\",\n                \"--eval\",\n                PROVIDER_LIFETIME_GUARDIAN_SOURCE,\n                providerBootstrap,\n                commandDirectoryPath,","sourceCodeStart":1354,"sourceCodeEnd":1390,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts#L1354-L1390","documentation":"When spawning the verified provider, the lease state must be consistent: a provider runtime executable lease (providerRuntimeExecutable) and its target environment variable name (providerRuntimeEnvironmentVariable) must either both be present or both be null. This internal-consistency check fires when exactly one of the two is set, meaning the executable lease object is in a half-initialized or corrupted state, so the child would get a runtime path without the env var naming it (or vice versa).","triggerScenarios":"spawn() on a VerifiedAcpxProvider whose internal providerRuntimeExecutable is non-null while providerRuntimeEnvironmentVariable is null, or vice versa — e.g. a lease built by an older/mismatched code path or partially released lease.","commonSituations":"Mixing versions of the runner and adapter-utils where one side populates the executable but not the env variable name; constructing the verified provider through a custom/introspection path; a prior close()/release cleared one field but not the other.","solutions":["Rebuild the verified provider via the library's normal verification/lease entry point so both fields are set together.","Check package versions: align paperclip-runner and adapter-utils so the lease producer matches this consumer.","Inspect the lease object: ensure providerRuntimeExecutable and providerRuntimeEnvironmentVariable are set as a pair (both null or both non-null).","If the lease was partially released, obtain a fresh lease instead of reusing it."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await provider.spawn(args, options, lifetime);\n} catch (err) {\n  if (err.message === \"ACPX provider runtime executable lease is invalid\") {\n    // lease is corrupted: rebuild via the library's verification entry point\n    provider = await createVerifiedAcpxProvider(...);\n  } else throw err;\n}","preventionTips":["Keep paperclip-runner and adapter-utils versions aligned","Treat the verified provider object as opaque; never mutate its lease fields","Re-create the provider after any close/release instead of reusing partial leases"],"tags":["internal-invariant-violation","process-spawn","state-mismatch"],"backgroundTag":"internal-invariant-violation","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"}