ACPX claude dependency package version mismatch for ${expect

Error message

ACPX claude dependency package version mismatch for ${expected.packageName}: expected ${expected.packageVersion}, received ${dependencyPackage.version ?? "unknown"}

What it means

After matching the declaration string, the resolver reads the actually-installed dependency's package.json and compares its version to the qualified packageVersion. This error fires when the version on disk differs from what qualification recorded — the declaration matched but the installed copy is a different release (or its version field is missing, reported as "unknown").

Source

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

    for (const expected of QUALIFIED_CLAUDE_PROVIDER_DEPENDENCIES) {
      if (
        (declaredDependencies as Record<string, unknown>)[
          expected.packageName
        ] !== expected.dependencyDeclaration
      ) {
        throw new Error(
          `ACPX claude package dependency mismatch for ${expected.packageName}`,
        );
      }
      const dependencyPackageJsonPath = await realpath(
        resolvePackageJson(expected.packageName, serverPackageJsonPath),
      );
      const dependencyPackage = await readPackageJson(
        dependencyPackageJsonPath,
        expected.packageName,
      );
      if (dependencyPackage.version !== expected.packageVersion) {
        throw new Error(
          `ACPX claude dependency package version mismatch for ${expected.packageName}: expected ${expected.packageVersion}, received ${dependencyPackage.version ?? "unknown"}`,
        );
      }
      supplementalPackages.push({
        directory: dirname(dependencyPackageJsonPath),
        format: packageModuleFormat(dependencyPackage.type),
      });
    }
  }

  const serverDependencyAncestors = await inspectDependencyAncestors(
    commandDirectory,
    packageDirectory,
    profile.agent,
  );
  const dependencyAncestors = [...serverDependencyAncestors];
  const dependencyAncestorFormats = serverDependencyAncestors.map(
    () => serverPackageFormat,

View on GitHub (pinned to 01ad858492)

Solutions

Reinstall dependencies from the lockfile (pnpm install --frozen-lockfile / npm ci) so the installed version equals the qualified packageVersion.
Deduplicate node_modules (pnpm dedupe / npm dedupe) so resolution finds the single qualified version.
Pin the dependency to the exact qualified version in the server package and reinstall.
If you must run a newer version, re-qualify the profile with the new packageVersion instead of forcing the old qualification.

Example fix

// before
$ npm update @anthropic-ai/claude-code  # installs 2.1.0, qualified was 2.0.14
// after
$ npm ci  # restores exact qualified 2.0.14 from lockfile

Defensive patterns

Strategy: validation

Validate before calling

for (const expected of QUALIFIED_CLAUDE_PROVIDER_DEPENDENCIES) {
  const depPkg = JSON.parse(fs.readFileSync(require.resolve(expected.packageName + "/package.json"), "utf8"));
  if (depPkg.version !== expected.packageVersion) {
    throw new Error(`pre-check: ${expected.packageName} installed ${depPkg.version}, qualified ${expected.packageVersion}`);
  }
}

Type guard

const versionMatches = (depPkg, expected) => depPkg?.version === expected.packageVersion;

Try / catch

try {
  await verifyQualifiedAcpxInstallation(input);
} catch (e) {
  if (/dependency package version mismatch/.test(e.message)) {
    execSync("npm ci"); // restore exact lockfile versions
    await verifyQualifiedAcpxInstallation(input);
  } else throw e;
}

Prevention

Never run bare `npm update`/`pnpm update` in the ACPX install tree; use frozen installs.
Dedupe node_modules regularly to avoid multiple copies resolving differently.
Re-qualify deliberately when intentionally upgrading a qualified dependency.

When it happens

Trigger: verifyQualifiedAcpxInstallation with profile.agent === "claude", where readPackageJson on the realpath of the resolved dependency returns version !== expected.packageVersion — e.g. hoisted duplicate at a different version, or semver-compatible newer release installed without updating the declaration.

Common situations: npm install with a caret range pulled a newer patch/minor than at qualification time; multiple copies of the dependency in a monorepo and resolution picked the wrong one; a partial upgrade left node_modules out of sync with package.json; corrupted install missing the version field.

Related errors

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