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

• License Activation Failed — canopy activate returns 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

• 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

• Slow Indexing — canopy index takes longer than expected. Large repos, binary files, missing .gitignore, embedding generation.
• Symbol Not Found — canopy_extract_symbol returns empty; canopy_search_symbols misses a known symbol.

Diagnostics

• Collect Diagnostic Logs — What to collect and how to send a complete support request.

---

For immediate help, email [email protected] with the output of canopy status and canopy license attached.