Troubleshooting

Symptom-based guides for fixing Forge issues. Each entry covers: symptoms, likely causes, step-by-step fix, and when to escalate.

Activation and Licensing

• License Activation Failed — forge activate returns an error. Invalid key format, expired key, wrong key, machine limit reached.
• License Revoked — Forge has degraded to Community Mode with a “license revoked” message.
• Air-Gapped Activation — Activating or using Forge 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 Forge. Wrong path, binary not in PATH, repo not indexed.
• Client Can’t Find forge — “command not found: forge”. How to install and add to PATH.

Indexing and Search

• Slow Indexing — forge index takes longer than expected. Large repos, binary files, missing .gitignore, embedding generation.
• Symbol Not Found — forge_extract_symbol returns empty; forge_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 forge status and forge license attached.