Troubleshooting

Common issues and how to fix them.

Quick Diagnostics

Start here to identify what's wrong:

# Check system health
shyp doctor

# Check app status
shyp status

# View PM2 processes
pm2 status

# View deployment logs
shyp logs my-app

# View PM2 logs
pm2 logs my-app

Deployment Issues

Git clone/pull fails

Usually an SSH key issue. Check that your deploy key is set up correctly.

# Test SSH connection to GitHub
ssh -T git@github.com

# Check SSH key is loaded
ssh-add -l

# Manually try to clone
git clone git@github.com:you/your-repo.git /tmp/test-clone

See the Prerequisites page for SSH key setup.

Build fails

Check the build logs and make sure dependencies are installed correctly.

# View deployment logs
shyp logs my-app

# Try building manually
cd /var/www/my-app
npm ci
npm run build

Common causes: missing environment variables, Node.js version mismatch, memory limits.

App starts but crashes immediately

Usually a missing environment variable or port conflict.

# Check PM2 logs for errors
pm2 logs my-app --lines 100

# Check if port is in use
sudo lsof -i :3001

# Restart with fresh state
pm2 delete my-app
shyp deploy my-app

Build runs out of memory

Node.js may need more heap memory for large builds.

apps/my-app.yaml

build:
  command: NODE_OPTIONS=--max-old-space-size=4096 npm run build

Nginx Issues

502 Bad Gateway

The app isn't running or Nginx can't connect to it.

# Check if app is running
pm2 status

# Check if app is listening on the expected port
curl http://localhost:3001

# Check Nginx error logs
sudo tail -f /var/log/nginx/error.log

Nginx config test fails

There's a syntax error in the Nginx configuration.

# Test Nginx config
sudo nginx -t

# View generated config
cat /etc/nginx/sites-available/my-app

# Regenerate configs
shyp sync

Domain not resolving

DNS might not be configured correctly.

# Check DNS resolution
dig +short yourdomain.com

# Should return your server's IP
# If not, check your DNS settings

SSL Issues

Certificate not obtained

Let's Encrypt couldn't verify your domain.

# Check DNS is pointing to your server
dig +short yourdomain.com

# Make sure port 80 is open
sudo ufw status

# Try obtaining cert manually
sudo certbot certonly --nginx -d yourdomain.com

Common causes: DNS not propagated, firewall blocking port 80, wrong server IP.

Certificate expired

Auto-renewal may have failed.

# Check certbot renewal timer
sudo systemctl status certbot.timer

# Try renewal manually
sudo certbot renew

# Force renewal if needed
sudo certbot renew --force-renewal

Webhook Issues

Webhook not received

Check that the webhook server is running and port 9000 is open.

# Check webhook server status
pm2 status shyp-webhook

# Check if port 9000 is open
sudo ufw allow 9000/tcp

# Test endpoint
curl http://YOUR_SERVER_IP:9000/health

Signature verification failed

The webhook secret doesn't match.

# Check your environment variable
echo $SHYP_WEBHOOK_SECRET

# Make sure it matches what's in GitHub
# Go to: Repo → Settings → Webhooks → Edit

Webhook received but no deploy

The repo URL or branch might not match.

# View webhook logs
pm2 logs shyp-webhook

# Check your app config
cat /etc/shyp/apps/my-app.yaml

# Verify the repo URL matches exactly

PM2 Issues

App keeps restarting

Usually a crash loop. Check logs for the error.

# View error logs
pm2 logs my-app --err --lines 50

# Check restart count
pm2 status

# Stop the crash loop to investigate
pm2 stop my-app

PM2 not starting on boot

PM2 startup script may not be configured.

# Configure PM2 startup
pm2 startup

# Save current process list
pm2 save

High memory usage

Set memory limits in your app config.

resources:
  memory: 512M  # PM2 will restart if exceeded

Still Stuck?

Check the logs: Most issues are revealed in shyp logs or pm2 logs.

Run diagnostics: shyp doctor checks for common configuration issues.

Open an issue: github.com/shypd/shyp/issues