Troubleshooting¶

Common issues and solutions.

Installation Issues¶

Docker Image Won't Pull¶

Error: manifest unknown or unauthorized

Solution:

# Verify image name
docker pull ghcr.io/taoshan98/ip-hop:latest

# Login if private
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

Container Exits Immediately¶

Check logs:

docker logs ip-hop

Common causes: - Missing environment variables - Database permission issues - Port conflicts

Runtime Issues¶

Cannot Access Frontend¶

Check container is running:
```
docker ps | grep ip-hop
```
Verify ports:
```
docker port ip-hop
```
Check firewall:
```
sudo ufw status
```

API Returns 500 Error¶

Check backend logs:
```
docker logs ip-hop 2>&1 | grep ERROR
```

Verify environment variables:

docker exec ip-hop env | grep SECRET_KEY

Database Locked¶

Error: database is locked

Solution:

# Stop container
docker stop ip-hop

# Check for multiple instances
docker ps -a | grep ip-hop

# Remove old instances
docker rm old-container-id

# Start fresh
docker start ip-hop

Provider Issues¶

Updates Failing¶

Test API credentials in provider dashboard
Check IP-HOP logs for specific errors
Verify provider API status (check provider status page)

IP Not Updating¶

Check update interval settings
Force manual update via UI

Verify current IP detection:

curl http://localhost:8001/api/v1/system/status

Performance Issues¶

High Memory Usage¶

Solution: Limit container resources:

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

Slow Response¶

Check container stats:
```
docker stats ip-hop
```

Verify database size:

docker exec ip-hop ls -lh /app/backend/database/

Restart container:
```
docker restart ip-hop
```

Network Issues¶

Cannot Access Remotely¶

Verify local access works first
Check router port forwarding
Verify firewall rules
Test with: telnet your-ip 3000

CORS Errors¶

Update API CORS settings:

API_CORS_ORIGINS=https://yourdomain.com

Still Having Issues?¶

Enable debug logging:
```
LOG_LEVEL=DEBUG
```
Collect logs:
```
docker logs ip-hop > iphop-logs.txt
```
Open GitHub Issue with:
IP-HOP version
Platform (Docker, Pi, etc.)
Error messages
Steps to reproduce

Report Issue