Troubleshooting
Symptom-based guides for fixing Canopy issues. Each entry covers: symptoms, likely causes, step-by-step fix, and when to escalate.
Activation and Licensing
Section titled “Activation and Licensing”- License Activation Failed —
canopy activatereturns an error. Invalid key format, expired key, wrong key, machine limit reached. - License Revoked — Canopy has degraded to Community Mode with a “license revoked” message.
- Air-Gapped Activation — Activating or using Canopy in an environment with no internet access.
- Admin Portal Access — Can’t log into the Team admin portal; magic link issues; invite token problems.
Binary and Startup
Section titled “Binary and Startup”- Binary Won’t Run on macOS — Gatekeeper blocks the binary with “unidentified developer”. Fix: remove quarantine attribute.
- MCP Server Won’t Start — AI client cannot connect to Canopy. Wrong path, binary not in PATH, repo not indexed.
- Client Can’t Find canopy — “command not found: canopy”. How to install and add to PATH.
Indexing and Search
Section titled “Indexing and Search”- Slow Indexing —
canopy indextakes longer than expected. Large repos, binary files, missing.gitignore, embedding generation. - Symbol Not Found —
canopy_answercan’t locate a symbol you know exists. Re-index, ignore rules, phrasing.
Diagnostics
Section titled “Diagnostics”- Collect Diagnostic Logs — What to collect and how to send a complete support request.
For immediate help, email support@gulfshieldtech.com with the output of canopy doctor and canopy license attached — doctor is the one-stop diagnostic (install info, index status, active backend, data-flow, credential presence).