{"record":{"id":"11ee9fc4b47bd82e","repo":"paperclipai/paperclip","slug":"qualified-acpx-runtime-package-omitted-its-version","errorCode":null,"errorMessage":"Qualified ACPX runtime package omitted its version","messagePattern":"Qualified ACPX runtime package omitted its version","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts","lineNumber":571,"sourceCode":"  const verifiedDirectory = await openVerifiedCommandDirectory(\n    commandDirectory,\n    profile.agent,\n  );\n  const commandDirectoryIdentity = verifiedDirectory.identity;\n  await verifiedDirectory.handle.close();\n  const command = await inspectCommand(\n    commandPath,\n    profile.commandDigest,\n    profile.agent,\n  );\n\n  let runtimePackageJsonPath: string | null = null;\n  let runtimePackageFormat: AcpxCommandFormat | null = null;\n  let runtimePackage: AcpxPackageMetadata | null = null;\n  let runtimeExecutable: VerifiedAcpxRuntimeExecutable | null = null;\n  if (profile.agentRuntimePackage !== null) {\n    if (profile.agentRuntimeVersion === null) {\n      throw new Error(\"Qualified ACPX runtime package omitted its version\");\n    }\n    runtimePackageJsonPath = await realpath(\n      resolvePackageJson(profile.agentRuntimePackage, serverPackageJsonPath),\n    );\n    runtimePackage = await readPackageJson(\n      runtimePackageJsonPath,\n      profile.agentRuntimePackage,\n    );\n    if (runtimePackage.version !== profile.agentRuntimeVersion) {\n      throw new Error(\n        `ACPX ${profile.agent} runtime version mismatch: expected ${profile.agentRuntimeVersion}, received ${runtimePackage.version ?? \"unknown\"}`,\n      );\n    }\n    runtimePackageFormat = packageModuleFormat(runtimePackage.type);\n    runtimeExecutable = await verifyQualifiedRuntimeExecutable({\n      profile,\n      runtimePackage,\n      runtimePackageJsonPath,","sourceCodeStart":553,"sourceCodeEnd":589,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts#L553-L589","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set profile.agentRuntimeVersion to the exact expected version string alongside agentRuntimePackage (e.g. \"1.2.3\").","Check the profile source (config file/JSON) for a missing or misnamed version field and fix the key.","Read the installed runtime's package.json version and pin the profile to that value so verification passes.","If no runtime package should be used, set agentRuntimePackage to null instead — note the symmetric rule that a version without a package also throws."],"exampleFix":"// before\nconst profile = { agent: \"claude\", agentServerPackage: \"@acpx/claude\", agentServerVersion: \"2.1.0\", agentRuntimePackage: \"@acpx/runtime\" /* version missing */ };\n// after\nconst profile = { agent: \"claude\", agentServerPackage: \"@acpx/claude\", agentServerVersion: \"2.1.0\", agentRuntimePackage: \"@acpx/runtime\", agentRuntimeVersion: \"1.4.2\" };","handlingStrategy":"validation","validationCode":"if (profile.agentRuntimePackage != null && profile.agentRuntimeVersion == null) {\n  throw new Error(\"agentRuntimePackage requires a matching agentRuntimeVersion\");\n}","typeGuard":"function hasPinnedRuntime(p: { agentRuntimePackage: string | null; agentRuntimeVersion: string | null }): p is { agentRuntimePackage: string; agentRuntimeVersion: string } & typeof p {\n  return p.agentRuntimePackage !== null && p.agentRuntimeVersion !== null;\n}","tryCatchPattern":"try {\n  const installation = await verifyQualifiedAcpxInstallation(profile);\n} catch (err) {\n  if (err instanceof Error && err.message === \"Qualified ACPX runtime package omitted its version\") {\n    // add the pinned agentRuntimeVersion to the profile and retry once\n  } else throw err;\n}","preventionTips":["Treat runtime package and version as an atomic pair in profile types and builders; never allow one without the other.","Use a schema validator (e.g. zod refinement) on profiles before passing them to verification.","Copy profiles wholesale rather than field-by-field to avoid dropping version fields.","Pin versions from the actually installed runtime's package.json so verification matches reality."],"tags":["config","pinned-versions","validation","profiles"],"backgroundTag":"missing-required-config-field","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}