paperclipai/paperclip · error

Qualified ACPX runtime version omitted its package

Error message

Qualified ACPX runtime version omitted its package

What it means

verifyQualifiedAcpxInstallation validates that the qualified ACPX profile is internally consistent before launching the agent runtime. A qualified profile pins both a runtime package (profile.agentRuntimePackage) and its exact version (profile.agentRuntimeVersion); this throw fires when a version is present but the package name is null, an impossible combination for a real qualified profile. It is an internal invariant check protecting against tampered or malformed profile construction.

Source

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

    );
    runtimePackage = await readPackageJson(
      runtimePackageJsonPath,
      profile.agentRuntimePackage,
    );
    if (runtimePackage.version !== profile.agentRuntimeVersion) {
      throw new Error(
        `ACPX ${profile.agent} runtime version mismatch: expected ${profile.agentRuntimeVersion}, received ${runtimePackage.version ?? "unknown"}`,
      );
    }
    runtimePackageFormat = packageModuleFormat(runtimePackage.type);
    runtimeExecutable = await verifyQualifiedRuntimeExecutable({
      profile,
      runtimePackage,
      runtimePackageJsonPath,
      resolvePackageJson,
    });
  } else if (profile.agentRuntimeVersion !== null) {
    throw new Error("Qualified ACPX runtime version omitted its package");
  }

  const supplementalPackages: Array<{
    directory: string;
    format: AcpxCommandFormat;
  }> = [];
  if (profile.agent === "claude") {
    const declaredDependencies = serverPackage.dependencies;
    if (
      typeof declaredDependencies !== "object" ||
      declaredDependencies === null ||
      Array.isArray(declaredDependencies)
    ) {
      throw new Error("ACPX claude package omitted its qualified dependencies");
    }
    for (const expected of QUALIFIED_CLAUDE_PROVIDER_DEPENDENCIES) {
      if (
        (declaredDependencies as Record<string, unknown>)[

View on GitHub (pinned to 01ad858492)

Solutions

1. Fix the source of the profile so agentRuntimePackage and agentRuntimeVersion are set together; inspect where the QualifiedAcpxProfile is built or loaded.
2. Re-generate or reset the qualified ACPX profile (clear any cached profile data) so both fields are populated consistently.
3. Validate the profile at load time (reject any profile where exactly one of package/version is null) to fail fast with a clearer message.

Example fix

// before
const profile = { agent: "claude", agentRuntimePackage: null, agentRuntimeVersion: "2.0.14" };
// after
const profile = { agent: "claude", agentRuntimePackage: "@zed-industries/claude-code-acp", agentRuntimeVersion: "2.0.14" };

function isValidQualifiedProfile(p) {
  return (p.agentRuntimePackage === null) === (p.agentRuntimeVersion === null);
}
if (!isValidQualifiedProfile(profile)) throw new Error("runtime package and version must be set together");

const hasConsistentRuntime = (p) =>
  (typeof p.agentRuntimePackage === "string" && typeof p.agentRuntimeVersion === "string") ||
  (p.agentRuntimePackage === null && p.agentRuntimeVersion === null);

try {
  await verifyQualifiedAcpxInstallation(input);
} catch (e) {
  if (e.message.includes("omitted its package")) {
    profile = await regenerateQualifiedProfile(); // rebuild from canonical source
  } else throw e;
}

When it happens

Trigger: Calling verifyQualifiedAcpxInstallation (via the installation entry point) with a QualifiedAcpxProfile where profile.agentRuntimePackage === null and profile.agentRuntimeVersion !== null. This can only arise if the profile was hand-built, deserialized from an unvalidated source, or constructed by a buggy code path.

Common situations: Profile JSON edited by hand or by a tool that dropped the package name but kept the version; a stale/corrupted qualified-profile cache after an upgrade changed the profile schema; custom adapter code constructing QualifiedAcpxProfile objects directly.

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 claude package omitted its qualified dependencies
• ACPX claude package dependency mismatch for ${expected.packa
• ACPX claude dependency package version mismatch for ${expect
• ACPX provider dependency ancestry exceeds its bound
• ACPX provider runtime executable identity changed after veri

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