Skip to main content

Troubleshooting

Common issues and solutions for AsaHome Cloud.

Quick Diagnostics​

Check Service Status​

# Docker containers
docker-compose ps

# Application health
curl http://localhost/api/v1/health

# View recent logs
docker-compose logs --tail=50

Common Health Check​

# All-in-one health check
make health

Connection Issues​

API Connection Refused​

Symptoms: curl: (7) Failed to connect to localhost port 80: Connection refused

Solutions:

  1. Check if containers are running:

    docker-compose ps

  2. Start containers:

    make up

  3. Check port availability:

    lsof -i :80
    lsof -i :3000

  4. View container logs:

    docker-compose logs app
    docker-compose logs nginx

WebSocket Connection Failed​

Symptoms: Socket.IO connection errors, "WebSocket is closed before the connection is established"

Solutions:

  1. Verify WebSocket endpoint:

    curl -i -N -H "Connection: Upgrade" \
      -H "Upgrade: websocket" \
      -H "Sec-WebSocket-Version: 13" \
      -H "Sec-WebSocket-Key: test" \
      http://localhost/tunnel

  2. Check Nginx WebSocket configuration:

    location /tunnel {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

  3. Verify CORS settings:

    grep CORS_ORIGINS .env

Authentication Issues​

Invalid Token Errors​

Symptoms: 401 Unauthorized, "Token has expired", "Invalid token"

Solutions:

  1. Check token expiration:

    • Access tokens expire in 15 minutes
    • Refresh token to get new access token

  2. Verify JWT_SECRET hasn't changed:

    # Same secret must be used across restarts
    grep JWT_SECRET .env

  3. Check token format:

    # Token should be in format: Bearer <token>
    curl -H "Authorization: Bearer YOUR_TOKEN" \
      http://localhost/api/v1/users/me

  4. Clear and re-authenticate:

    • Logout and login again
    • If using mobile app, clear app data

Refresh Token Errors​

Symptoms: "Refresh token has been revoked", "Refresh token has expired"

Solutions:

  1. Token rotation: Each refresh invalidates the previous token
  2. Re-authenticate: Login again to get new tokens
  3. Check database: 
    SELECT * FROM refresh_tokens 
    WHERE userId = 'user-uuid' 
    ORDER BY createdAt DESC;

Password Validation Errors​

Symptoms: "Invalid email or password" with correct credentials

Solutions:

  1. Check user exists:

    SELECT id, email, isActive FROM users WHERE email = 'user@example.com';

  2. Verify user is active:

    UPDATE users SET isActive = true WHERE email = 'user@example.com';

  3. Reset password manually:

    // Generate new hash
    const bcrypt = require('bcrypt');
    const hash = await bcrypt.hash('newpassword', 12);
    UPDATE users SET password = '<hash>' WHERE email = 'user@example.com';

Database Issues​

Connection Failed​

Symptoms: "ECONNREFUSED", "Connection terminated unexpectedly"

Solutions:

  1. Check PostgreSQL is running:

    docker-compose ps postgres
    docker-compose logs postgres

  2. Verify connection settings:

    grep DB_ .env

  3. Test connection:

    make shell-db
    # or
    docker-compose exec postgres psql -U postgres -d asahome_cloud

  4. Restart PostgreSQL:

    docker-compose restart postgres

Migration Errors​

Symptoms: "relation does not exist", "column does not exist"

Solutions:

  1. Check migration status:

    npm run migration:show

  2. Run pending migrations:

    npm run migration:run

  3. Revert and retry:

    npm run migration:revert
    npm run migration:run

  4. Reset database (development only):

    docker-compose down -v
    docker-compose up -d postgres
    npm run migration:run

Database Full​

Symptoms: "could not extend file", disk space errors

Solutions:

  1. Check disk space:

    df -h
    docker system df

  2. Clean up Docker:

    docker system prune -a

  3. Clean up old refresh tokens:

    DELETE FROM refresh_tokens 
    WHERE expiresAt < NOW() - INTERVAL '7 days';

Device Issues​

Device Shows Offline​

Symptoms: Device isOnline: false despite being connected

Solutions:

  1. Check device heartbeat:

    SELECT uuid, isOnline, lastSeenAt FROM devices 
    WHERE uuid = 'device-uuid';

  2. Verify device WebSocket connection:

    • Check device logs for connection errors
    • Verify device token hasn't expired

  3. Force heartbeat update:

    curl -X POST http://localhost/api/v1/devices/heartbeat/DEVICE_UUID \
      -H "Authorization: Bearer DEVICE_TOKEN"

Device Not Receiving Commands​

Symptoms: Commands sent but device doesn't respond

Solutions:

  1. Verify device socket registration:

    • Check WebSocket gateway logs
    • Ensure device connected with device token (not user token)

  2. Check device UUID matches:

    SELECT * FROM devices WHERE uuid = 'device-uuid';

  3. Test tunnel directly:

    socket.on('tunnel:message', (data) => {
      console.log('Received:', data);
    });

Performance Issues​

Slow API Responses​

Symptoms: API requests taking > 1 second

Solutions:

  1. Enable database query logging:

    DB_LOGGING=true

  2. Check for N+1 queries: Review TypeORM relations

  3. Add database indexes:

    CREATE INDEX CONCURRENTLY idx_devices_userId 
    ON device_users(userId);

  4. Check container resources:

    docker stats

High Memory Usage​

Symptoms: Container OOM killed, memory errors

Solutions:

  1. Check memory limits:

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

  2. Monitor memory:

    docker stats --no-stream

  3. Check for memory leaks:

    • Review WebSocket connection handling
    • Ensure proper cleanup on disconnect

WebSocket Connection Drops​

Symptoms: Frequent disconnections, reconnection loops

Solutions:

  1. Increase Nginx timeouts:

    proxy_read_timeout 86400s;
    proxy_send_timeout 86400s;

  2. Enable keep-alive:

    proxy_set_header Connection "";

  3. Check rate limiting: Ensure not hitting connection limits

Docker Issues​

Container Won't Start​

Symptoms: Container exits immediately, status "Exited"

Solutions:

  1. View exit logs:

    docker-compose logs app

  2. Check for missing env vars:

    docker-compose config

  3. Rebuild container:

    docker-compose build --no-cache app
    docker-compose up -d

Permission Denied​

Symptoms: "permission denied" errors in container

Solutions:

  1. Fix file permissions:

    chmod -R 755 ./

  2. Run as correct user:

    # docker-compose.yml
    services:
      app:
        user: "node"

Out of Disk Space​

Symptoms: "no space left on device"

Solutions:

  1. Clean Docker resources:

    docker system prune -a --volumes

  2. Remove old images:

    docker image prune -a

  3. Clean build cache:

    docker builder prune

Debugging Commands​

View All Logs​

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f app

# Last N lines
docker-compose logs --tail=100 app

Database Shell​

make shell-db
# or
docker-compose exec postgres psql -U postgres -d asahome_cloud

Application Shell​

docker-compose exec app sh

Check Environment​

docker-compose exec app env | grep -E "(DB_|JWT_|NODE_)"

Test Endpoints​

# Health check
curl http://localhost/api/v1/health

# Login
curl -X POST http://localhost/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "password": "password"}'

Getting Help​

If you're still stuck:

  1. Check logs thoroughly: Most issues are visible in logs
  2. Search existing issues: Check if others encountered the same problem
  3. Gather information: Collect logs, error messages, environment details
  4. Contact support: Include all relevant diagnostic information