ACPX ${input.profile.agent} runtime executable package versi

Error message

ACPX ${input.profile.agent} runtime executable package version mismatch: expected ${qualification.packageVersion}, received ${executablePackage.version ?? "unknown"}

What it means

The verifier resolves the platform executable package referenced by the runtime, reads its package.json, and requires its version to exactly equal the hash-pinned qualification.packageVersion. A mismatch means the installed executable package is not the audited build whose digest will be checked next, so the runner refuses to use it.

Source

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

    ] !== qualification.dependencyDeclaration
  ) {
    throw new Error(
      `ACPX ${input.profile.agent} runtime omitted its verified platform executable package`,
    );
  }

  const executablePackageJsonPath = await realpath(
    input.resolvePackageJson(
      qualification.packageName,
      input.runtimePackageJsonPath,
    ),
  );
  const executablePackage = await readPackageJson(
    executablePackageJsonPath,
    qualification.packageName,
  );
  if (executablePackage.version !== qualification.packageVersion) {
    throw new Error(
      `ACPX ${input.profile.agent} runtime executable package version mismatch: expected ${qualification.packageVersion}, received ${executablePackage.version ?? "unknown"}`,
    );
  }

  const packageDirectory = dirname(executablePackageJsonPath);
  const unresolvedExecutablePath = resolve(
    packageDirectory,
    qualification.relativeExecutable,
  );
  if (!isInside(packageDirectory, unresolvedExecutablePath)) {
    throw new Error(
      `ACPX ${input.profile.agent} runtime executable escapes its package`,
    );
  }
  const executableDirectory = await realpath(dirname(unresolvedExecutablePath));
  if (!isInsideOrEqual(packageDirectory, executableDirectory)) {
    throw new Error(
      `ACPX ${input.profile.agent} runtime executable escapes its package`,

View on GitHub (pinned to 01ad858492)

Solutions

Compare installed version vs expected in the message (expected qualification.packageVersion) and install exactly that version of the platform executable package.
Regenerate the lockfile entry and reinstall: remove the platform package from node_modules and lockfile, then pnpm/npm install so versions re-sync with the runtime.
Align profile.agentRuntimeVersion with the installed runtime so qualification and disk state agree.
Check for overrides/resolutions/link: deps in the root package.json that redirect the platform package to a different version, and remove them.
Verify the resolved path (PAPERCLIP_ACPX_PROVIDER_PACKAGE_ROOT if set) contains the pinned build, not a locally built variant.

Example fix

// before
pnpm add @paperclip/acpx-codex-linux-x64@latest
// after: pin the qualified version
pnpm add @paperclip/acpx-codex-linux-x64@1.2.3 --save-exact

Defensive patterns

Strategy: validation

Validate before calling

const pkg = JSON.parse(fs.readFileSync(execPkgJsonPath, "utf8"));
if (pkg.version !== expectedVersion) {
  throw new Error(`Platform package at ${execPkgJsonPath} is ${pkg.version ?? "unknown"}, need ${expectedVersion}; pin it exactly`);
}

Prevention

Pin platform executable packages with exact versions (no ^/~) in the lockfile.
Keep runtime and platform packages installed together from one lockfile; never partially upgrade one.
Check root package.json overrides/resolutions and link:/file: deps that can redirect the platform package.
Confirm PAPERCLIP_ACPX_PROVIDER_PACKAGE_ROOT (if set) hosts the pinned build.

When it happens

Trigger: The optional platform package (e.g. @paperclip/acpx-codex-linux-x64) resolved on disk is a different version than the qualification pin — stale node_modules, a lockfile drift, a semver-range install that pulled a newer release, or PAPERCLIP_ACPX_PROVIDER_PACKAGE_ROOT pointing at a tree with a different build.

Common situations: Upgrading the runtime but not reinstalling the platform package (or vice versa); npm dedupe/hoisting resolving an older/newer copy; local link:/file: overrides; a fresh environment restored from a partial lockfile; package.json version field missing (reported as 'unknown') because of a broken tarball.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

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