paperclipai/paperclip · error · Error

Verified ACPX installation does not match its profile

Error message

Verified ACPX installation does not match its profile

What it means

During ACPX runtime host open(), the installation is verified via verifyQualifiedAcpxInstallation (or a dependency override), and the resulting commandDigest is compared against the command digest pinned in the profile. This error means the on-disk/verified ACPX executable differs from the one the profile was built for, so the host refuses to launch an unverified binary.

Source

Thrown at packages/paperclip-runner/src/drivers/acpx/runtime-host.ts:315

    if (
      options.agent !== "codex" &&
      options.managedCodexCredentialSourcePath !== undefined
    ) {
      throw new Error(
        "Managed Codex credentials require the Codex ACPX profile",
      );
    }

    const installation = await runAbortableAdmissionStage(
      options.signal,
      () =>
        (dependencies.verifyInstallation ?? verifyQualifiedAcpxInstallation)(
          profile,
        ),
      dependencies.retainAdmissionCleanup,
    );
    if (installation.commandDigest !== profile.commandDigest) {
      throw new Error("Verified ACPX installation does not match its profile");
    }
    let command: VerifiedAcpxCommandLease | null = null;
    let credential: AcpxProviderLifetimeLease | null = null;
    let toolBridge: RunnerToolBridge | null = null;
    let runtime: AcpxRuntimePort | null = null;
    let pendingRuntimeOwnsCredential = false;
    const admissionVerificationTimeoutMs =
      dependencies.admissionVerificationTimeoutMs ??
      RUNTIME_ADMISSION_VERIFICATION_TIMEOUT_MS;
    const admissionCleanupTimeoutMs =
      dependencies.admissionCleanupTimeoutMs ??
      RUNTIME_ADMISSION_VERIFICATION_TIMEOUT_MS;
    let failedAdmissionCleanupTransferred = false;
    let resolveFailedAdmissionCleanupTransfer!: () => void;
    const failedAdmissionCleanupTransfer = new Promise<void>((resolve) => {
      resolveFailedAdmissionCleanupTransfer = resolve;
    });
    const retainFailedAdmissionCleanup = (cleanup: Promise<void>): void => {

View on GitHub (pinned to 01ad858492)

Solutions

1. Recreate/refresh the ACPX profile so its commandDigest matches the currently installed executable
2. Pin the ACPX version so upgrades do not occur mid-session and reopen with a matching profile
3. If a custom dependencies.verifyInstallation is injected, ensure it returns an installation whose commandDigest equals profile.commandDigest
4. Delete stale runtime/session state referencing the old profile and retry open()

Example fix

// before
const host = await open({ profile: staleProfile });
// after
const profile = await rebuildAcpxProfile(currentInstallation); // digest matches binary
const host = await open({ profile });

const installation = await verifyQualifiedAcpxInstallation(profile);
if (installation.commandDigest !== profile.commandDigest) {
  throw new Error("Profile digest is stale; rebuild profile before open()");
}

function isProfileCurrent(installation, profile) {
  return installation?.commandDigest === profile?.commandDigest;
}

try {
  const host = await open({ profile });
} catch (err) {
  if (err.message === "Verified ACPX installation does not match its profile") {
    const freshProfile = await rebuildAcpxProfile();
    return open({ profile: freshProfile });
  }
  throw err;
}

When it happens

Trigger: Calling open() when the ACPX binary on disk changed (upgrade, downgrade, reinstall, PATH change) after the profile recorded its commandDigest, or when verifyInstallation is stubbed/returns a mismatched installation.

Common situations: ACPX was auto-updated between profile creation and runtime open; multiple ACPX versions installed and PATH resolves a different one; a cached/stale profile from a previous session; CI images rebuilt with a different toolchain version.

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

• ACPX runtime does not expose session goal controls
• ACPX runtime host is closing
• ACPX runtime host already has an active turn
• Workspace reseed returned without a verified terminal manife
• Native ACPX backend for pi is unavailable until descriptor-c

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