{"record":{"id":"7d1f4ac434e14b42","repo":"paperclipai/paperclip","slug":"qualified-acpx-runtime-version-omitted-its-package","errorCode":null,"errorMessage":"Qualified ACPX runtime version omitted its package","messagePattern":"Qualified ACPX runtime version omitted its package","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts","lineNumber":593,"sourceCode":"    );\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,\n      resolvePackageJson,\n    });\n  } else if (profile.agentRuntimeVersion !== null) {\n    throw new Error(\"Qualified ACPX runtime version omitted its package\");\n  }\n\n  const supplementalPackages: Array<{\n    directory: string;\n    format: AcpxCommandFormat;\n  }> = [];\n  if (profile.agent === \"claude\") {\n    const declaredDependencies = serverPackage.dependencies;\n    if (\n      typeof declaredDependencies !== \"object\" ||\n      declaredDependencies === null ||\n      Array.isArray(declaredDependencies)\n    ) {\n      throw new Error(\"ACPX claude package omitted its qualified dependencies\");\n    }\n    for (const expected of QUALIFIED_CLAUDE_PROVIDER_DEPENDENCIES) {\n      if (\n        (declaredDependencies as Record<string, unknown>)[","sourceCodeStart":575,"sourceCodeEnd":611,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts#L575-L611","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the source of the profile so agentRuntimePackage and agentRuntimeVersion are set together; inspect where the QualifiedAcpxProfile is built or loaded.","Re-generate or reset the qualified ACPX profile (clear any cached profile data) so both fields are populated consistently.","Validate the profile at load time (reject any profile where exactly one of package/version is null) to fail fast with a clearer message."],"exampleFix":"// before\nconst profile = { agent: \"claude\", agentRuntimePackage: null, agentRuntimeVersion: \"2.0.14\" };\n// after\nconst profile = { agent: \"claude\", agentRuntimePackage: \"@zed-industries/claude-code-acp\", agentRuntimeVersion: \"2.0.14\" };","handlingStrategy":"validation","validationCode":"function isValidQualifiedProfile(p) {\n  return (p.agentRuntimePackage === null) === (p.agentRuntimeVersion === null);\n}\nif (!isValidQualifiedProfile(profile)) throw new Error(\"runtime package and version must be set together\");","typeGuard":"const hasConsistentRuntime = (p) =>\n  (typeof p.agentRuntimePackage === \"string\" && typeof p.agentRuntimeVersion === \"string\") ||\n  (p.agentRuntimePackage === null && p.agentRuntimeVersion === null);","tryCatchPattern":"try {\n  await verifyQualifiedAcpxInstallation(input);\n} catch (e) {\n  if (e.message.includes(\"omitted its package\")) {\n    profile = await regenerateQualifiedProfile(); // rebuild from canonical source\n  } else throw e;\n}","preventionTips":["Always construct QualifiedAcpxProfile via a single factory that sets package and version together.","Validate profiles at deserialization time with a schema (zod/JSON schema) requiring both-or-neither.","Never hand-edit qualified profile files; regenerate them from the qualification flow."],"tags":["installation-integrity","acpx","internal-invariant","config"],"backgroundTag":"internal-invariant-violation","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"}