---
topic: troubleshooting
source_keys:
  - context7-microsoft-apm
---

## Manifest / lockfile ref mismatch

Happens when the version or ref declared in `apm.yml` no longer matches what's recorded in the stale `apm.lock.yaml`:

```text
<owner>/<repo>: manifest ref 'v2' != lockfile ref 'v1'
N ref mismatch(es) -- run 'apm install' to update lockfile
```

Fix: run `apm install` to reconcile the lockfile with the manifest.

## Missing lockfile

Occurs when a command that needs a resolved dependency graph runs before the first install:

```text
lockfile not found at apm.lock.yaml; run 'apm install' to generate it
```

## Lockfile version mismatch

The installed `apm` binary is older than the lockfile format it's being asked to read:

```text
[x] apm.lock.yaml uses lockfile_version "2", this binary supports "1"
    [>] Upgrade APM: see https://...
```

Fix: upgrade the APM binary to a version that supports the newer lockfile schema.

## Content hash mismatch (possible supply-chain issue)

Raised when downloaded dependency bytes don't match the hash recorded in the lockfile:

```text
[x] Content hash mismatch for <owner>/<repo>: expected <sha>, got <sha>.
The downloaded content differs from the lockfile record. This may
indicate a supply-chain attack. Use 'apm install --update' to accept
new content and update the lockfile.
```

This is a fail-closed integrity check — treat an unexpected occurrence as a security signal, not just a stale-cache annoyance. Only use `apm install --update` once you've confirmed the new upstream content is legitimate (e.g., a real re-tag), since it deliberately overwrites the recorded hash.

## Dependency version conflicts

Direct and transitive dependency constraints are resolved by intersecting version ranges. Example: a manifest directly depends on `acme/foo#^1.2.0`, and a transitive dependency (`acme/bar`) pulls in `acme/foo#^1.5.0`. The effective constraint is the intersection, `[>=1.5.0, <2.0.0)`, and APM picks the highest tag in that range. If the two constraints don't overlap at all (e.g. `^1.2.0` vs. `^2.0.0`), resolution fails closed rather than silently picking one side — install errors out instead of guessing.