Troubleshooting
Common issues
Fixes for frequent setup and usage problems.
Cannot sign in
AI chat stuck or 202 never completes
Confirm Redis:
redis-cli ping → PONG.Confirm agent:
curl http://localhost:8100/health.Check agent logs for LLM API key errors (
LLM_PROVIDER, Gemini/Anthropic/OpenAI keys).Verify stream names match between backend and agent .env (AI_REQUIREMENTS_QUEUE_*).
Ensure you are a project member with sufficient role.
OAuth (Google / GitHub) fails
| Check | Action |
|---|---|
| Redirect URI mismatch | Register http://localhost:8000/api/auth/callback/{provider} |
BETTER_AUTH_URL | Must be http://localhost:8000, not the Next.js port |
| Client ID/secret | Set GOOGLE_* or GITHUB_* in backend .env |
Linear sync issues
- Reconnect at
/dashboard/organization/integrations - Confirm project link on
.../linearpage - Inspect
GET /projects/:id/linear/sync-runsfor last error - Webhooks require a public URL in staging/production
Documentation editor
- Hard refresh after deploy
- Confirm project membership
- Check browser Network tab for
403fromProjectMemberGuard
Docs site (this app)
| Issue | Fix |
|---|---|
| Empty Cmd+K search | Run pnpm build once to index content |
| Ask AI errors | Set OPENROUTER_API_KEY in ragnarock-docs/.env.local |
| Mermaid blank | Hard refresh; toggle theme (diagram re-renders on theme change) |
Still blocked?
Collect:
- API response body and status from Network tab
- Relevant backend log line (NestJS)
- Agent worker stack trace
- Output of
pnpm docs:scanif the issue is missing documentation
Open an issue with these details in your team's tracker.