| name | constellation-troubleshooting |
| description | This skill should be used when the user asks about "Constellation errors", "fix Constellation", "debug Constellation", "Constellation not working", "API connection issues", "indexing problems", "MCP server", "Failed to reconnect", mentions any Constellation error codes (AUTH_ERROR, PROJECT_NOT_INDEXED, etc.), or when Constellation commands fail. |
Constellation Troubleshooting
Diagnose Constellation plugin failures. If unavailable, continue with local search/read and clearly note degraded mode.
Triage Order
- If
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 code_intel.
- Restart Cursor.
- 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.
