Troubleshooting

Troubleshooting

🌍 English translation is auto-generated on release. See the French version for the current complete page.

Common issues, diagnostic commands, log locations, and how to open a good bug report.

Troubleshooting

Most build and connection problems fall into a handful of categories, each with a documented fix.

Claude authentication — If the agent pipeline fails to authenticate, check ~/.claude/profiles.json for the active profile, or trigger a token refresh via the UI or refresh_all_tokens() in main.claude_profile.token_refresh. Expired tokens are resolved by running claude and re-running /login; invalid API keys should be checked directly in your environment variables, and persistent OAuth issues usually mean revoking and reauthorizing the app.

Cross-platform build issues — Never hardcode paths or rely on process.platform. Use the platform abstraction helpers (isWindows(), findExecutable(), joinPaths()) from core.platform (backend) or apps/frontend/src/main/platform/ (frontend) — CI exercises all three supported OSes, so platform-specific shortcuts tend to fail there even when they work locally.

grepai connectivity — Confirm the server is up with curl http://localhost:9000/health; if it's down, start it via python grepai_launcher.py in src/connectors/grepai. Semantic search silently falls back to standard grep when grepai is unavailable, so a missing server degrades functionality rather than breaking it outright.

Memory system (Graphiti) — Verify connectivity with check_connection() in integrations.graphiti.client, and enable it with GRAPHITI_ENABLED=true if it isn't already active.

Performance — For slow or unresponsive runs, check logs/workflow.log for detailed traces, and consider reducing the number of concurrent agents in settings.

Issue	First step
Auth failures	Check ~/.claude/profiles.json, refresh tokens
Cross-platform build errors	Use core.platform / frontend platform helpers
grepai unreachable	curl http://localhost:9000/health, relaunch if needed
Memory/Graphiti errors	check_connection(), set GRAPHITI_ENABLED=true
Slow or stuck runs	Review logs/workflow.log, lower concurrent agent count

When none of the above resolves the issue, pytest tests/ -v from the backend virtual environment surfaces test failures with more context, and logs/workflow.log remains the primary source of truth for tracing what each agent, skill, or hook actually did during a run.

---

➡️ Continue: Roadmap