EC2 Troubleshooting and Common Issues Fixing Node.js Deployment Problems

EC2 Troubleshooting and Common Issues

Deploying Node.js on EC2 comes with common issues. This guide covers the most frequent problems and their solutions.

1. Cannot SSH into EC2

Symptom: Connection timed out or Permission denied.

Solutions:

# Check if the instance is running (AWS Console)
# Check security group   port 22 open for your IP
# Check key file permissions
chmod 400 your-key.pem

# Connect with verbose output for debugging
ssh -v -i your-key.pem ubuntu@your-ip

# If your IP changed, update the security group

Common causes:

• Security group SSH rule is set to 0.0.0.0/0 or wrong IP
• Key file permissions are too open (must be 400)
• Instance is stopped
• Wrong username (use ubuntu for Ubuntu AMIs)

2. Nginx 502 Bad Gateway

Symptom: Browser shows "502 Bad Gateway".

Cause: Nginx can't connect to the Node.js backend.

Solutions:

# Check if Node.js app is running
pm2 status

# If not running, start it
pm2 start src/server.js --name devtinder-api

# Check PM2 logs for errors
pm2 logs devtinder-api --lines 50

# Verify Nginx proxy_pass matches the app port
sudo cat /etc/nginx/sites-enabled/devtinder

# Check if port 3000 is listening
sudo netstat -tlnp | grep 3000

# Restart both
pm2 restart devtinder-api
sudo systemctl restart nginx

3. Nginx 404 Not Found

Symptom: API returns 404 for all routes.

Cause: Nginx configuration is wrong or the default site is still enabled.

Solutions:

# Ensure default site is removed
sudo rm /etc/nginx/sites-enabled/default

# Verify your config is enabled
ls -la /etc/nginx/sites-enabled/

# Test config
sudo nginx -t

# Restart
sudo systemctl restart nginx

4. PM2 App Crashes Immediately

Symptom: pm2 status shows "errored" or the app restarts repeatedly.

Solutions:

# Check error logs
pm2 logs devtinder-api --err --lines 50

# Common causes:
# - Missing .env file (create it)
# - MongoDB connection failed (check MONGODB_URI)
# - Port already in use (change PORT or kill the process)
# - Missing dependencies (run npm install)

# Clear PM2 logs and restart
pm2 flush
pm2 restart devtinder-api

5. SSL Certificate Renewal Fails

Symptom: certbot renew --dry-run fails.

Solutions:

# Check Certbot logs
sudo cat /var/log/letsencrypt/letsencrypt.log

# Common causes:
# - Port 80 is not accessible (Let's Encrypt uses HTTP-01 challenge)
# - Nginx config has errors
# - Domain DNS has changed

# Test Nginx config
sudo nginx -t

# Ensure port 80 is open in security group
# Verify domain still points to EC2 IP

6. Socket.io Not Working

Symptom: Chat doesn't work, no real-time updates.

Solutions:

# Check Nginx WebSocket configuration
sudo cat /etc/nginx/sites-enabled/devtinder

# Ensure the /socket.io/ location block has:
# proxy_http_version 1.1;
# proxy_set_header Upgrade $http_upgrade;
# proxy_set_header Connection "upgrade";

# Check browser console for WebSocket errors
# Ensure CLIENT_URL in backend .env matches frontend URL

7. High CPU Usage

Symptom: Instance is slow or unresponsive.

Solutions:

# Check top processes
top

# Check PM2 monit
pm2 monit

# Common causes:
# - Memory leak in Node.js (restart PM2: pm2 restart devtinder-api)
# - Too many concurrent requests (upgrade instance type)
# - Infinite loop in code (check PM2 logs)
# - Nginx worker processes (check nginx -t and worker_processes config)

# Check available memory
free -h

# Check disk space
df -h

8. Out of Disk Space

Symptom: Cannot write files, app crashes with disk errors.

Solutions:

# Check disk usage
df -h

# Find large files
sudo du -sh /* | sort -rh | head -10

# Clear PM2 logs (they can grow large)
pm2 flush

# Clear Nginx logs
sudo truncate -s 0 /var/log/nginx/access.log
sudo truncate -s 0 /var/log/nginx/error.log

# Clear apt cache
sudo apt clean

9. MongoDB Connection Timeout

Symptom: App crashes with MongoDB connection timeout.

Solutions:

# Check if MongoDB URI is correct
cat .env | grep MONGODB

# For Atlas, ensure IP is whitelisted
# Add your EC2 IP to Atlas Network Access

# Test connection from EC2
mongosh "mongodb+srv://your-connection-string"

# Check if the database is accessible
ping your-cluster.mongodb.net

10. CORS Errors After Deployment

Symptom: Frontend gets CORS errors in browser console.

Solutions:

# Check backend CORS configuration
# Ensure CLIENT_URL matches the frontend URL exactly

# In app.js:
# app.use(cors({
#   origin: process.env.CLIENT_URL,
#   credentials: true
# }));

# In .env:
# CLIENT_URL=https://your-frontend-domain.com

The Takeaway

Common EC2 issues include SSH connection problems, Nginx 502/404 errors, PM2 crashes, SSL renewal failures, Socket.io WebSocket issues, high CPU, out of disk space, MongoDB timeouts, and CORS errors. The key to troubleshooting is checking logs (PM2 logs, Nginx logs, Certbot logs), verifying configurations, and testing each component in isolation.