Saltar al contenido principal

Debugging and Troubleshooting Runbook

This guide provides systematic approaches to debugging and resolving common issues within the AlphaSwarm platform.

Quick Reference: Enable Debug Mode​

Backend (Worker & Agents)​

Set the log level to DEBUG in your environment:

export ALPHASWARM_LOG_LEVEL=DEBUG

Frontend (Next.js)​

No alphaswarm_debug localStorage flag was found in alphaswarm_ui or alphaswarm_client as of this review — use the browser devtools network/console panes and the framework's own verbose flags (e.g. next dev output) until a dedicated debug toggle ships.

Common Issues and Solutions​

1. API Connectivity Issues​

Symptom: Frontend shows "API Unavailable" or 504 errors.

  • Check: Is the alphaswarm-api pod running?
  • Command: kubectl get pods -l app=alphaswarm-api
  • Solution: Check logs for crash loops: kubectl logs -l app=alphaswarm-api --tail=100.

2. Worker/Agent Failures​

Symptom: Backtests or trades are stuck in PENDING or FAILED.

  • Check: Celery/Ray worker logs.
  • Command: alphaswarm-cli bots logs <bot-id>
  • Solution: Often due to missing credentials or unreachable data sources (e.g., QuestDB).

3. Database Connection Issues​

Symptom: "Connection refused" to PostgreSQL or Neo4j.

  • Check: Service endpoints and passwords.
  • Solution: Verify DATABASE_URL and NEO4J_PASSWORD environment variables match the secret store.

Observability Tools​

  • Loki/Grafana: Centralized log search and metric dashboards.
  • Sentry: Error tracking and alerting.
  • AlphaSwarm CLI: Use alphaswarm status system for a quick health check.

Systematic Debugging Steps​

  1. Isolate the Component: Is it the UI, API, Worker, or Database?
  2. Check Logs: Always start with tail -f on the relevant component.
  3. Verify Environment: Run alphaswarm-cli setup verify to check prerequisites and env vars.
  4. Reproduce Locally: Use the local dev stack (make dev) to reproduce the issue in a controlled environment.

Further Documentation​

  • For incident response procedures, see Incident Response.
  • For detailed architecture, see Architecture Index.
  • For project-wide index, see the AlphaSwarm Index (alphaswarm_index repo).