Skip to main content

Common Issues

Solutions to frequently encountered problems with Bloqd.

Dashboard Issues​

Can't Access Dashboard​

Symptom: Browser shows connection refused or timeout.

Solutions:

  1. Check if container is running:

    docker compose ps

  2. Check container logs:

    docker compose logs bloqd

  3. Verify port is exposed:

    docker compose port bloqd 3000

  4. Check firewall:

    # Allow port 3000 (or your configured port)
    sudo ufw allow 3000/tcp

Dashboard Loads But Shows Errors​

Symptom: Dashboard loads but displays API errors.

Solutions:

  1. Check API health:

    curl http://localhost:3000/api/v1/health

  2. Check database connection:

    docker compose logs bloqd | grep -i database

  3. Restart the container:

    docker compose restart bloqd

Blank White Page​

Symptom: Dashboard shows blank white page.

Solutions:

  1. Clear browser cache - Hard refresh (Ctrl+Shift+R)

  2. Check browser console - F12 → Console tab for JavaScript errors

  3. Verify static files:

    docker compose exec bloqd ls -la /app/frontend/dist

Login Issues​

Can't Log In​

Symptom: Login fails with "Invalid credentials".

Solutions:

  1. Reset admin password:

    docker compose exec bloqd npm run reset-password admin

  2. Check if user exists:

    docker compose exec bloqd sqlite3 /app/data/bloqd.db \
      "SELECT username FROM users;"

  3. Create new admin user:

    docker compose exec bloqd npm run create-user -- \
      --username newadmin \
      --password "YourPassword123" \
      --role admin

Session Expires Too Quickly​

Symptom: Logged out frequently.

Solutions:

  1. Increase session timeout in .env:

    SESSION_TIMEOUT=86400  # 24 hours

  2. Check system time synchronization:

    # Container time
    docker compose exec bloqd date

    # Host time
    date

OAuth Login Fails​

Symptom: GitHub/Google login redirects back with error.

Solutions:

  1. Verify callback URL:

    • GitHub: https://bloqd.example.com/api/v1/auth/github/callback
    • Google: https://bloqd.example.com/api/v1/auth/google/callback

  2. Check OAuth credentials in .env:

    GITHUB_CLIENT_ID=your_client_id
    GITHUB_CLIENT_SECRET=your_secret

  3. Ensure HTTPS is configured correctly

Server Connection Issues​

Server Shows "Offline"​

Symptom: Server shows offline status in dashboard.

Solutions:

  1. Check agent on server:

    sudo systemctl status bloqd-agent

  2. Check agent logs:

    sudo journalctl -u bloqd-agent -n 50

  3. Test connectivity from agent:

    curl -v https://bloqd.example.com/api/v1/health

  4. Verify agent configuration:

    sudo cat /etc/bloqd/agent.yaml

  5. Restart agent:

    sudo systemctl restart bloqd-agent

Server Shows "Pending"​

Symptom: Newly added server stuck in pending state.

Solutions:

  1. Complete installation - Run the installer script on the server

  2. Check token validity:

    # On dashboard server
    docker compose logs bloqd | grep "install token"

  3. Regenerate install command from dashboard

Heartbeat Errors​

Symptom: Agent reports heartbeat failures.

Solutions:

  1. Check network connectivity:

    ping bloqd.example.com

  2. Check SSL certificate:

    openssl s_client -connect bloqd.example.com:443

  3. Check agent API key:

    grep api_key /etc/bloqd/agent.yaml

Ban Issues​

Bans Not Showing​

Symptom: Fail2ban is banning IPs but they don't appear in dashboard.

Solutions:

  1. Check reporter module:

    grep -i reporter /etc/bloqd/agent.yaml

  2. Check fail2ban action:

    sudo cat /etc/fail2ban/action.d/bloqd.conf

  3. Test manual ban report:

    sudo fail2ban-client set sshd banip 192.168.1.100
    # Then check dashboard
    sudo fail2ban-client set sshd unbanip 192.168.1.100

  4. Check agent logs:

    journalctl -u bloqd-agent | grep -i "ban"

Whitelist Not Working​

Symptom: Whitelisted IPs still getting banned.

Solutions:

  1. Check whitelist sync:

    # On managed server
    sudo cat /etc/fail2ban/jail.local | grep ignoreip

  2. Force sync:

    # From dashboard API
    curl -X POST "https://bloqd.example.com/api/v1/whitelist/sync" \
      -H "Authorization: Bearer f2b_your_api_key"

  3. Reload fail2ban:

    sudo fail2ban-client reload

Manual Ban/Unban Fails​

Symptom: Manual ban/unban commands don't work.

Solutions:

  1. Check command queue:

    curl "https://bloqd.example.com/api/v1/commands/queue" \
      -H "Authorization: Bearer f2b_your_api_key"

  2. Check agent command module:

    grep -i command /etc/bloqd/agent.yaml

  3. Check fail2ban status:

    sudo systemctl status fail2ban
    sudo fail2ban-client status

Performance Issues​

Dashboard Slow​

Symptom: Dashboard takes long time to load.

Solutions:

  1. Check server resources:

    docker stats bloqd

  2. Check database size:

    ls -lh ./data/bloqd.db

  3. Reduce ban retention:

    BAN_RETENTION_DAYS=30

  4. Vacuum database:

    sqlite3 ./data/bloqd.db "VACUUM;"

High Memory Usage​

Symptom: Container using excessive memory.

Solutions:

  1. Restart container:

    docker compose restart bloqd

  2. Limit container memory:

    # docker-compose.yml
    services:
      bloqd:
        deploy:
          resources:
            limits:
              memory: 512M

API Timeouts​

Symptom: API requests timeout.

Solutions:

  1. Check database locks:

    sqlite3 ./data/bloqd.db "PRAGMA busy_timeout=5000;"

  2. Check pending commands:

    curl "https://bloqd.example.com/api/v1/commands/queue" \
      -H "Authorization: Bearer f2b_your_api_key" | jq '.pending'

SSL/TLS Issues​

Certificate Errors​

Symptom: Browser shows certificate warning.

Solutions:

  1. Check certificate validity:

    openssl s_client -connect bloqd.example.com:443 2>/dev/null | \
      openssl x509 -noout -dates

  2. Renew Let's Encrypt:

    sudo certbot renew

  3. Check certificate chain:

    curl -vI https://bloqd.example.com 2>&1 | grep -i certificate

Mixed Content Warnings​

Symptom: Browser console shows mixed content errors.

Solutions:

  1. Ensure BASE_URL uses HTTPS:

    BASE_URL=https://bloqd.example.com

  2. Check reverse proxy headers:

    proxy_set_header X-Forwarded-Proto $scheme;

Docker Issues​

Container Won't Start​

Symptom: Container exits immediately.

Solutions:

  1. Check logs:

    docker compose logs bloqd

  2. Check environment file:

    docker compose config

  3. Verify volume permissions:

    ls -la ./data/
    chmod 755 ./data/

Permission Denied Errors​

Symptom: Permission errors in container logs.

Solutions:

  1. Fix data directory permissions:

    sudo chown -R 1000:1000 ./data/

  2. Run container as root (not recommended for production):

    services:
      bloqd:
        user: root

Out of Disk Space​

Symptom: Container fails with disk space errors.

Solutions:

  1. Clean Docker system:

    docker system prune -a

  2. Check disk usage:

    df -h
    du -sh ./data/*

  3. Remove old images:

    docker image prune -a

Getting Help​

If your issue isn't listed here:

  1. Check agent-specific issues - See Agent Issues
  2. Check license issues - See License Issues
  3. Review FAQ - See FAQ
  4. Search GitHub Issues - https://github.com/clusterzx/bloqd/issues
  5. Enable debug logging: 
    LOG_LEVEL=debug