paperclipai/paperclip · error

Qualified ACPX runtime package omitted its version

Error message

Qualified ACPX runtime package omitted its version

What it means

verifyQualifiedAcpxInstallation validates a qualified agent profile: when profile.agentRuntimePackage is set (non-null), a matching profile.agentRuntimeVersion is mandatory so the runtime package's installed version can be compared exactly. This error is thrown when a profile names a runtime package but omits its pinned version, making the qualification unverifiable — the verifier fails closed rather than allowing an unpinned runtime.

Source

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

  const verifiedDirectory = await openVerifiedCommandDirectory(
    commandDirectory,
    profile.agent,
  );
  const commandDirectoryIdentity = verifiedDirectory.identity;
  await verifiedDirectory.handle.close();
  const command = await inspectCommand(
    commandPath,
    profile.commandDigest,
    profile.agent,
  );

  let runtimePackageJsonPath: string | null = null;
  let runtimePackageFormat: AcpxCommandFormat | null = null;
  let runtimePackage: AcpxPackageMetadata | null = null;
  let runtimeExecutable: VerifiedAcpxRuntimeExecutable | null = null;
  if (profile.agentRuntimePackage !== null) {
    if (profile.agentRuntimeVersion === null) {
      throw new Error("Qualified ACPX runtime package omitted its version");
    }
    runtimePackageJsonPath = await realpath(
      resolvePackageJson(profile.agentRuntimePackage, serverPackageJsonPath),
    );
    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,

View on GitHub (pinned to 01ad858492)

Solutions

1. Set profile.agentRuntimeVersion to the exact expected version string alongside agentRuntimePackage (e.g. "1.2.3").
2. Check the profile source (config file/JSON) for a missing or misnamed version field and fix the key.
3. Read the installed runtime's package.json version and pin the profile to that value so verification passes.
4. If no runtime package should be used, set agentRuntimePackage to null instead — note the symmetric rule that a version without a package also throws.

Example fix

// before
const profile = { agent: "claude", agentServerPackage: "@acpx/claude", agentServerVersion: "2.1.0", agentRuntimePackage: "@acpx/runtime" /* version missing */ };
// after
const profile = { agent: "claude", agentServerPackage: "@acpx/claude", agentServerVersion: "2.1.0", agentRuntimePackage: "@acpx/runtime", agentRuntimeVersion: "1.4.2" };

if (profile.agentRuntimePackage != null && profile.agentRuntimeVersion == null) {
  throw new Error("agentRuntimePackage requires a matching agentRuntimeVersion");
}

function hasPinnedRuntime(p: { agentRuntimePackage: string | null; agentRuntimeVersion: string | null }): p is { agentRuntimePackage: string; agentRuntimeVersion: string } & typeof p {
  return p.agentRuntimePackage !== null && p.agentRuntimeVersion !== null;
}

try {
  const installation = await verifyQualifiedAcpxInstallation(profile);
} catch (err) {
  if (err instanceof Error && err.message === "Qualified ACPX runtime package omitted its version") {
    // add the pinned agentRuntimeVersion to the profile and retry once
  } else throw err;
}

When it happens

Trigger: Constructing/passing an ACPX agent profile where `agentRuntimePackage` is a package name string but `agentRuntimeVersion` is left null/undefined; deserializing a profile from config where the version field was dropped or renamed; hand-editing a qualified profile and deleting the version.

Common situations: Typo'd field name in profile config (e.g. runtimeVersion instead of agentRuntimeVersion); partial profile copy that carries the package but not the version; upgrading the verifier schema so previously optional versions became required.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• ${label} is not a regular file at ${canonical}.
• Claude Managed evals require exact model claude-sonnet-5
• AWS AgentCore evals require exact model global.anthropic.cla
• request.session.provider must match request.provider
• request.session.requestedModel must match request.model

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