Troubleshooting
Solutions to common SkyPort issues.
Installation Issues
"Command not found: skyport"
Problem: After installation, skyport command is not recognized.
Solution:
# Verify installation
which skyport
# If not found, add to PATH
export PATH="/usr/local/bin:$PATH"
# Make permanent (Linux/macOS)
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Windows:
- Restart your terminal after installation
- If still not working, manually add
C:\Program Files\SkyPortto your PATH - Restart your computer if necessary
Permission Denied on Linux
Problem: Permission denied when trying to run skyport
Solution:
# Make binary executable
chmod +x /usr/local/bin/skyport
# Verify permissions
ls -la /usr/local/bin/skyport
Server Issues
"Address already in use" Error
Problem: Port 8080 is already in use
Solution:
# Use a different port
skyport start webui --port 8081
# Or find and stop the process using the port
lsof -i :8080 # Linux/macOS
netstat -ano | findstr :8080 # Windows
# Kill the process
kill -9 <PID> # Linux/macOS
taskkill /PID <PID> /F # Windows
SkyPort Crashes on Start
Problem: Server crashes immediately after starting
Solution:
# Check if configuration is corrupted
rm -rf ~/.skyport/config.yaml
# Clear cache
rm -rf ~/.skyport/cache
# Restart
skyport start webui
WebUI Won't Load
Problem: Dashboard shows blank or doesn't load
Solution:
- Clear browser cache (Ctrl+Shift+Delete)
- Try incognito/private mode
- Check browser console for errors (F12)
- Try a different browser
- Restart SkyPort server
Docker Issues
Docker Socket Permission Error
Problem: "Permission denied" when accessing Docker socket
Solution (Linux):
# Add current user to docker group
sudo usermod -aG docker $USER
newgrp docker
# Verify
docker ps
Solution (macOS):
# Docker Desktop should handle permissions automatically
# If issues persist, restart Docker Desktop
Solution (Windows with WSL2):
# Inside WSL2, run:
sudo usermod -aG docker $USER
Cannot Connect to Docker Daemon
Problem: "Cannot connect to Docker daemon"
Solution:
# Ensure Docker is running
sudo systemctl start docker # Linux
# Or open Docker Desktop # macOS/Windows
# Check Docker socket location
ls -la /var/run/docker.sock # Linux
# Try restarting Docker
sudo systemctl restart docker # Linux
Image Pull Fails
Problem: Cannot pull Docker images
Solution:
# Check internet connection
ping docker.io
# Check DNS
nslookup docker.io
# Try with explicit registry
skyport docker pull docker.io/library/nginx:latest
# Configure Docker daemon if behind proxy
# Edit /etc/docker/daemon.json
PM2 Issues
PM2 Command Not Found
Problem: skyport pm2 commands don't work
Solution:
# Install PM2 globally
npm install -g pm2
# Or use Node.js directly
node /path/to/pm2/bin/pm2.js list
Application Won't Start with PM2
Problem: PM2 app won't start
Solution:
# Check if Node.js is installed
node --version
# Check the start script
skyport pm2 describe app-name
# View detailed error logs
skyport pm2 logs app-name --err
# Try starting manually first
node app.js
PM2 Logs Not Showing
Problem: Cannot view PM2 application logs
Solution:
# Check log file location
skyport pm2 describe app-name
# View log files directly
tail -f ~/.pm2/logs/app-name-error.log
tail -f ~/.pm2/logs/app-name-out.log
# Clear logs and restart
skyport pm2 flush
skyport pm2 restart app-name
Network Issues
Cannot Access Dashboard
Problem: Cannot access http://localhost:8080
Solution:
# Verify SkyPort is running
ps aux | grep skyport
# Check if port is listening
netstat -tuln | grep 8080 # Linux/macOS
netstat -ano | findstr :8080 # Windows
# Check firewall
sudo ufw status # Linux
# Verify with curl
curl http://localhost:8080
Reverse Proxy Not Working
Problem: Custom domain not routing to application
Solution:
# Check reverse proxy configuration
skyport proxy list
# Verify DNS is pointing to SkyPort
nslookup yourdomain.com
# Test proxy routing
curl -H "Host: yourdomain.com" http://localhost
# Check Caddy logs
skyport logs caddy -f
Cannot Reach Remote SkyPort
Problem: Cannot access SkyPort dashboard from another machine
Solution:
- Verify firewall allows port 8080
- Use the server's IP address:
http://server-ip:8080 - Don't use
localhostfrom a remote machine - Check if SkyPort is bound to
0.0.0.0:
netstat -tuln | grep 8080
Performance Issues
High CPU Usage
Problem: SkyPort or applications consuming too much CPU
Solution:
# Check CPU usage
skyport metrics cpu
# Identify heavy processes
top # Linux/macOS
tasklist # Windows
# Limit container CPU
skyport docker update --cpus 1 container-name
# Check for infinite loops or bugs in application
skyport docker logs container-name
Out of Memory
Problem: Applications killed due to OOM
Solution:
# Check memory usage
skyport metrics memory
# View container memory limits
skyport docker inspect container-name | grep Memory
# Increase memory limit
skyport docker update --memory 2g container-name
# Add swap (if on Linux)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
Slow Response Times
Problem: Dashboard or applications responding slowly
Solution:
# Check system resources
skyport system info
# Check disk I/O
iostat -x 1 # Linux
# Check network latency
ping 8.8.8.8
# Reduce number of running applications
skyport docker ps
Data Persistence Issues
Volumes Not Persisting Data
Problem: Container data is lost after restart
Solution:
# Always mount volumes
skyport docker run -d -v data-volume:/app/data my-app
# Verify volume exists
skyport docker volume ls
# Check volume mount in container
skyport docker inspect container-name | grep Mounts
Cannot Access Configuration Files
Problem: Configuration stored in /root/.skyport is not accessible
Solution:
# Check directory permissions
ls -la ~/.skyport
# Change permissions if needed
chmod 755 ~/.skyport
# Backup configuration
cp -r ~/.skyport ~/.skyport.backup
Getting More Help
- Check logs for detailed error messages
- Visit GitHub Issues
- Read Architecture Guide
- Check CLI Reference
Still stuck? Open an issue on GitHub with detailed logs and error messages.