Troubleshooting

Something broke. Find your symptom in the table, follow the link.

Triage by symptom

Symptom	Go to
Don’t recognize the error message	Common errors
apm install failed (auth, network, lockfile, cache, partial)	Install failures
apm compile exited 0 but no files were written	Compile produced no output
TLS verification failed, unable to get local issuer certificate	SSL / TLS issues
Install blocked by org policy, rule violation, allowlist mismatch	Debugging policy failures
Migrating from awd-cli, lockfile schema bump, target switch	Migration paths

When to escalate

If you’re past the relevant page and still stuck, gather these and open an issue:

apm --version
APM_DEBUG=1 apm <failing-command> --verbose 2>&1 | tee /tmp/apm-debug.log
apm cache info

Attach the log, your apm.yml, your apm.lock.yaml, and the apm cache info output to the APM issue tracker.

Related references

• Environment variables — everything APM reads from the shell.
• apm cache — diagnose and recover the local cache.
• apm policy — inspect what policy applies and why.