| name | troubleshooting |
| description | Use when the user encounters Constellation errors, connection issues, or needs help debugging code intelligence problems. Triggers for: "Constellation errors", "fix Constellation", "debug Constellation", "Constellation not working", "API connection issues", "indexing problems", "MCP server issues", error codes like AUTH_ERROR, PROJECT_NOT_INDEXED
|
| allowed-tools | code_intel |
Constellation Troubleshooting
Diagnose Constellation plugin failures. If unavailable, continue with local search/read and clearly note degraded mode.
Triage Order
- If
mcp__constellation__code_intel cannot be called, treat as MCP startup/config issue.
- If a response includes
error.code, branch by code:
AUTH_ERROR, PROJECT_NOT_INDEXED, SYMBOL_NOT_FOUND, FILE_NOT_FOUND, API_UNREACHABLE.
- If status is unclear, run
/constellation:status then /constellation:diagnose.
MCP Server Issues
Symptom: connection failures or missing mcp__constellation__code_intel.
- Restart Copilot CLI.
- Verify MCP binary:
npx -y @constellationdev/mcp@latest --version
- Verify MCP config points to
npx -y @constellationdev/mcp@latest and passes CONSTELLATION_ACCESS_KEY.
Authentication Issues (AUTH_ERROR)
Symptom: invalid credentials.
- Configure credentials:
npx @constellationdev/cli auth
- Read
error.guidance[0] for key-state details.
- Regenerate expired/revoked keys in Constellation UI.
Indexing Issues (PROJECT_NOT_INDEXED)
Symptom: index missing/stale.
- Index:
constellation index --full
- Force reindex:
constellation index --full --force
Connectivity Issues (API_UNREACHABLE)
Symptom: timeout or refusal.
- Check local network/DNS.
- Check status page:
https://status.constellationdev.io/
- Verify API URL in
constellation.json.
Query Issues (SYMBOL_NOT_FOUND, FILE_NOT_FOUND)
Usually not fatal; item is absent from index/query scope.
- Broaden search terms.
- Check spelling/case/path.
- Confirm language/extension is indexed.
- Reindex if files were added recently.
When blocked, continue task with local tools and state degraded mode.
Error Code Quick Reference
| Code | Cause | Fix |
|---|
AUTH_ERROR | Missing/invalid/expired API key | constellation auth |
PROJECT_NOT_INDEXED | Project needs indexing | constellation index --full |
SYMBOL_NOT_FOUND | Typo or stale index | Broader search or re-index |
FILE_NOT_FOUND | Path mismatch or stale index | Verify path; re-index |
API_UNREACHABLE | API not running / network issue | Check network, status page, API URL |
See references/error-codes.md for the complete error code reference.
