Common issues and solutions.
Bot Issues
Bot Won't Start
- Check logs:
docker compose logs tux - Verify BOT_TOKEN in
.env - Check database connection
- Verify all required env vars set
Bot Shows Offline
- Check token validity
- Verify internet connection
- Check Discord API status
- Review connection logs
Commands Not Working
- Wait for Discord sync (1-2 min)
- Verify bot permissions
- Check user permission ranks
- Try
/dev sync_tree
Database Issues
Can't Connect
- Check PostgreSQL running:
docker compose ps tux-postgres - Verify connection details in
.env - Test connection:
uv run db health
Migration Failures
- Check migration status:
uv run db status - Review migration logs
- Try:
uv run db reset
Performance Issues
High CPU Usage
- Check for infinite loops in logs
- Monitor database queries:
uv run db queries - Review error rate
High Memory Usage
- Check connection pool size
- Monitor with:
docker stats tux - Restart if needed
Discord Issues
Permission Errors
- Verify bot has required Discord permissions
- Check bot role hierarchy
- Re-invite bot with correct scopes
Rate Limiting
- Check Discord API status
- Reduce command usage
- Wait for rate limit to reset
Need Help?
Comprehensive troubleshooting guide in progress.