Common Errors

Found a confusing error? Search this page first. Each entry shows the error string APM prints, the underlying cause, and the shortest fix. Deeper guides are linked under “See also”.

Errors are grouped by the surface that produces them: install, compile, audit, run, and auth/network.

Install

`apm.yml not found. Run 'apm init' first.`

apm.yml not found. Run 'apm init' first.

Cause: APM was invoked in a directory with no manifest, or the manifest has a different name.

Fix: run apm init to scaffold a manifest, or cd into the project that owns the apm.yml.

`lockfile not found at <path>; run 'apm install' to generate it`

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

Cause: a command that needs a resolved dependency graph (drift check, audit, compile against lockfile) ran before the project had ever been installed.

Fix: run apm install once to produce apm.lock.yaml, then re-run the original command.

`<pkg>: not found in lockfile`

(message similar to)

<owner>/<repo>: not found in lockfile
1 ref mismatch(es) -- run 'apm install' to update lockfile

Cause: a dependency exists in apm.yml but has no entry in apm.lock.yaml. Most often hit in CI when the lockfile was not regenerated after editing the manifest.

Fix: run apm install locally to refresh apm.lock.yaml and commit the result. Do not hand-edit the lockfile.

`<pkg>: manifest ref '<ref>' != lockfile ref '<ref>'`

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

Cause: the version or ref pinned in apm.yml was changed without re-running install. The lockfile is stale.

Fix: run apm install and commit the updated apm.lock.yaml.

See also: Install failures

`Drift detected: N file(s)`

[!] Drift detected: N file(s)
[i] Run 'apm install' to re-sync deployed files with the lockfile.

Cause: deployed primitive files in the project differ from the content recorded in apm.lock.yaml. Either the files were edited locally, or the lockfile was updated without re-running install.

Fix: run apm install to re-deploy from the cache. If the local edits were intentional, vendor them into the source package or a local override before re-installing.

See also: Install failures

`Content hash mismatch for <pkg>: expected <a>, got <b>`

[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.

Cause: the bytes APM downloaded for a locked dependency do not match the content_hash recorded in apm.lock.yaml. Usually a force-pushed tag, a mutated branch, or a tampered mirror.

Fix: investigate the upstream package before accepting. If the change is legitimate, run apm install --update to re-pin and commit the new hash.

`Install blocked by org policy -- see violations above`

[x] Install blocked by org policy -- see violations above

Cause: an org-level policy (compilation target, dependency allowlist, security baseline) rejected one or more dependencies. The per-violation lines printed above this message identify the offending packages and rules.

Fix: read the violations above the summary line, remove or replace the offending packages, or update org policy if the rule is wrong.

`from unapproved host(s): <host>`

(message similar to)

[x] Refusing to install from unapproved host(s): <host>.

Cause: a dependency resolves to a host outside the configured allowlist.

Fix: add the host to the allowlist, or pass --allow-insecure-host <host> for a one-off install. Do not bypass the allowlist in CI.

`Race condition: concurrent checkout failed integrity for <url> @ <sha>`

Race condition: concurrent checkout failed integrity for <url> @ <sha>

Cause: two apm install processes raced on the same cache shard and the loser’s integrity check failed. The cache shard lock is per-shard with a 120s default timeout.

Fix: re-run apm install. If it reproduces, ensure only one install runs at a time per APM_CACHE_DIR. In CI, give each job its own cache directory.

See also: Install failures

Compile

`No primitives matched`

(message similar to) printed when compile produces zero output.

Cause: no primitives in the project (or filtered subset) match the active target’s compilation rules. Common causes: wrong --target, missing frontmatter, glob filter matched nothing, or org policy stripped everything.

Fix: run apm compile --dry-run --verbose to see what was discovered and why each primitive was skipped.

`[x] No harness detected`

[x] No harness detected

Cause: the project has no harness markers (.github/copilot-instructions.md, .claude/, .cursor/, …) and no targets: block in apm.yml. APM no longer defaults to copilot.

Fix: pass --target <harness> on the command, or declare targets: in apm.yml. Run apm targets to list supported harnesses.

`[x] Multiple harnesses detected: <a>, <b>`

Cause: APM found markers for more than one harness and cannot pick.

Fix: pin a target with --target <harness> or declare targets: in apm.yml. Use apm install --dry-run to preview each option.

`[x] Unknown target '<value>'`

[x] Unknown target '<value>'
Valid targets: claude, copilot, cursor, ...

Cause: the value passed to --target (or listed in apm.yml targets:) is not a known harness.

Fix: run apm targets for the canonical list. Check for typos.

Audit

`Policy violation: <dep> -- <reason>`

[x] Policy violation: <owner>/<repo>@<ref> -- <reason>

Cause: a dependency failed an org policy check during install or audit. The reason field names the rule.

Fix: see Policy debugging for resolving each rule type. For audit-only reporting, use apm audit --format sarif or --format json to feed the findings into your code-scanning pipeline.

`Policy hash mismatch from <source>: expected <a>, got <b>`

Cause: the org policy file fetched from the configured source does not match the pinned hash. Either the policy was updated upstream and the pin is stale, or the source was tampered with.

Fix: confirm the upstream change is legitimate, then update the policy pin in your APM config to the new hash.

Run

`Script or prompt '<name>' not found.`

Script or prompt '<name>' not found.
Available scripts in apm.yml: <list>

Cause: apm run <name> could not match <name> to a script in apm.yml, an auto-discovered prompt file, or an installable virtual package.

Fix: check the available scripts list printed under the error. To list discoverable prompts, run apm list. To install a remote prompt, use apm install <owner>/<repo>/path/to/prompt.prompt.md.

`No such command '<x>'`

Error: No such command '<x>'.

Cause: standard Click error. The subcommand does not exist, or you are on an older APM version that lacks it.

Fix: run apm --help for the current command list. Upgrade APM if the command was added in a newer release.

Auth and network

`GitHub API throttle for <host> (HTTP <status>)`

GitHub API throttle for github.com (HTTP 429)

Cause: GitHub conclusively throttled a virtual-file API probe. APM treats this as unknown rather than claiming the dependency is missing. It makes one sparse Git attempt; a later sparse Git transport failed message identifies a separate Git connectivity or authorization problem.

Fix: for public repositories, retry after the GitHub quota recovers if the sparse Git attempt also failed. For private repositories, configure the normal GitHub credential chain (for example GITHUB_APM_PAT) and confirm that the token can read the repository. A 401, ordinary 403, or 404 is not a throttle and requires fixing authentication, authorization, or the dependency path instead.

`Authentication failed for <host>`

[x] Authentication failed for <host>
... -- check `gh auth status` and `GITHUB_APM_PAT`

Cause: the remote host rejected APM’s credentials, or no credentials were available. Token resolution order for GitHub: per-org GITHUB_APM_PAT_<ORG>, then GITHUB_APM_PAT, then GITHUB_TOKEN, then GH_TOKEN, then gh auth token, then git credential helpers.

Fix: set GITHUB_APM_PAT (or run gh auth login) with a token that has access to the dependency’s repo. For Azure DevOps, set ADO_APM_PAT. The diagnostic block printed under the error names the host and the resolution attempts that failed.

See also: Install failures

`TLS verification failed`

TLS verification failed -- APM uses the system trust store by default.
If you're behind a corporate proxy or firewall, make sure your
organisation's CA is installed in the OS trust store, or set
REQUESTS_CA_BUNDLE to a readable PEM bundle and retry.

Cause: Python’s TLS stack rejected the server certificate. Almost always a corporate proxy doing TLS interception with a CA that is not in the system trust store.

Fix: install the corporate CA into the OS trust store and retry. For a per-shell override, export REQUESTS_CA_BUNDLE=/path/to/corporate-ca.pem; SSL_CERT_FILE alone is not a reliable requests override. Do not disable TLS verification.

Network timeout or host unreachable

(no fixed string; surfaces as requests / git transport errors after the 15s API or 30s git timeout)

Cause: the host is unreachable, the proxy is down, or DNS is failing.

Fix: confirm curl -v https://<host> works from the same shell. Check HTTPS_PROXY / NO_PROXY are set correctly. Re-run apm install --verbose to see which host failed and on which leg (API probe vs git fetch).