paperclipai/paperclip · error · Error

ACPX provider runtime executable lease is invalid

Error message

ACPX provider runtime executable lease is invalid

What it means

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).

Source

Thrown at packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts:1372

          : DEPENDENCY_ANCESTOR_FD_START +
            dependencyAncestors.length +
            providerRuntimeExecutableCount;
        const runtimeHandoff =
          verifiedRuntimeExecutableHandoff(runtimeTargetFd);
        const environment = sanitizedNodeEnvironment(options.env);
        delete environment[ACPX_PRIVATE_SNAPSHOT_ENV];
        if (privateSnapshot) environment[ACPX_PRIVATE_SNAPSHOT_ENV] = JSON.stringify(privateSnapshot.handoff);
        if (runtimeHandoff.environmentValue === undefined) {
          delete environment[VERIFIED_RUNTIME_EXECUTABLE_ENV];
        } else {
          environment[VERIFIED_RUNTIME_EXECUTABLE_ENV] =
            runtimeHandoff.environmentValue;
        }
        if (
          (providerRuntimeExecutable === null) !==
          (providerRuntimeEnvironmentVariable === null)
        ) {
          throw new Error("ACPX provider runtime executable lease is invalid");
        }
        if (providerRuntimeEnvironmentVariable === null) {
          delete environment[VERIFIED_PROVIDER_RUNTIME_TARGET_ENV];
        } else {
          environment[VERIFIED_PROVIDER_RUNTIME_TARGET_ENV] =
            providerRuntimeEnvironmentVariable;
        }
        child = spawnChildProcess(
          runtimeHandoff.executable,
          guarded
            ? [
                // Keep resolved module URLs on the retained descriptor paths
                // so the hook can distinguish them from host ancestry.
                "--preserve-symlinks",
                "--eval",
                PROVIDER_LIFETIME_GUARDIAN_SOURCE,
                providerBootstrap,
                commandDirectoryPath,

View on GitHub (pinned to 01ad858492)

Solutions

1. Rebuild the verified provider via the library's normal verification/lease entry point so both fields are set together.
2. Check package versions: align paperclip-runner and adapter-utils so the lease producer matches this consumer.
3. Inspect the lease object: ensure providerRuntimeExecutable and providerRuntimeEnvironmentVariable are set as a pair (both null or both non-null).
4. If the lease was partially released, obtain a fresh lease instead of reusing it.

try {
  await provider.spawn(args, options, lifetime);
} catch (err) {
  if (err.message === "ACPX provider runtime executable lease is invalid") {
    // lease is corrupted: rebuild via the library's verification entry point
    provider = await createVerifiedAcpxProvider(...);
  } else throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• ACPX provider credential fence is invalid
• ACPX provider package ancestry is invalid
• The setup-token login session could not start.
• ACPX provider dependency ancestry is invalid
• ACPX provider runtime executable count is invalid

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