Ravindra BagaleCourses & study guides

Appendix A: Troubleshooting Checklist

By Last updated:

Mitranno, when something breaks, ghabru naka (don't panic). Work through the list from outside to inside — most problems are found in the first few steps.

A.1 Cannot SSH into the instance

Check How
Instance is running and status checks 2/2 EC2 console
Correct public IP (changes after stop/start) Console → Instance → Public IPv4
Security group allows TCP 22 from your current IP (mobile hotspot / college Wi-Fi IPs change!) SG inbound rules → My IP
Correct username ec2-user (AL/CentOS Stream), ubuntu (Ubuntu), centos (old CentOS)
Correct key and permissions chmod 400 key.​pem / icacls on Windows; key pair name shown in console
Subnet has route 0.0.0.0/0 → Internet Gateway VPC → Route tables
Network ACL allows 22 inbound and ephemeral ports outbound VPC → Network ACLs
College/office network blocks outbound port 22 Try mobile hotspot, or use EC2 Instance Connect / Session Manager
Verbose output ssh -​v -​i key.​pem ec2-​user@IP

Common error messages:

Message Meaning
Connection timed out Network/security group/NACL/wrong IP
Connection refused Host reachable but sshd not running (rare on EC2)
Permission denied (publickey) Wrong user name or wrong key
UNPROTECTED PRIVATE KEY FILE Key permissions too open → chmod 400
REMOTE HOST IDENTIFICATION HAS CHANGED New instance reused the same IP → ssh-​keygen -​R <IP>

A.2 Website not loading

  1. curl -I http://localhost on the server — works? If not, the problem is on the server (step 3 onwards).
  2. From your laptop: curl -I http://<PUBLIC_IP> — timeout → security group (80/443), firewalld, NACL, public IP, typed https.
  3. sudo service nginx status (or httpd / apache2) — running? sudo nginx -t / apachectl configtest — syntax OK?
  4. sudo ss -tlnp | grep -E ':80|:443' — who is listening? Two web servers fighting for port 80?
  5. Read the error log (/var/log/nginx/error.log, /var/log/httpd/error_log, /var/log/apache2/error.log).
  6. 403 → permissions (namei -l <file>), missing index file, SELinux (restorecon -Rv, ls -Z).
  7. 404 → wrong root / DocumentRoot / file name case.
  8. 502/504 → backend app down or wrong port; curl 127.0.0.1:<port>; pm2 status; sudo service <app> status; CentOS: setsebool -P httpd_can_network_connect 1.
  9. 500 → application error; check app logs (journalctl -u <app>, pm2 logs, PHP-FPM log).

A.3 Database problems

Symptom Check
Can't connect sudo service mariadb status / mysql / mongod; sudo ss -​tlnp | grep -​E '3306|​27017'
Access denied User/host/password: SELECT user,​host FROM mysql.​user;
Works locally, not from another server bind-address/bindIp, security group from the app server's SG only
mongod won't start sudo tail -​50 /​var/​log/​mongodb/​mongod.​log; disk full? permissions on data dir? SELinux?

A.4 Server problems

Symptom Check
Disk full df -h, sudo du -​h --​max-​depth=​1 / | sort -​h, clear old logs sudo journalctl --​vacuum-​size=​200M, grow EBS
Out of memory / processes killed free -h, dmesg | grep -​i oom, add swap, bigger instance type
High CPU top/htop; T-instance CPU credits exhausted? (CloudWatch CPUCreditBalance)
Instance won't boot after editing fstab Stop instance, detach root volume, attach to a helper instance, fix fstab, re-attach (or use EC2 Serial Console)
Service not starting at boot systemctl is-​enabled <svc>; sudo systemctl enable <svc>; pm2 startup + pm2 save
Website/SSH broken after stop/start or type change Public IP changed — attach an Elastic IP (Chapter 14)
Time zone wrong in logs sudo timedatectl set-​timezone Asia/​Kolkata

A.5 Web-server configuration and domains

Symptom Check / fix
403 after changing root / DocumentRoot namei -l <file> (755 dirs, 644 files); matching <Directory> with Require all granted; CentOS SELinux: ls -Z, semanage fcontext -​a -​t httpd_​sys_​content_​t "/​path(/.*)?" + restorecon -Rv; never serve from home folders
New port not reachable sudo ss -tlnp (listening?); security group inbound rule; firewall-​cmd --​add-​port=​PORT/​tcp; CentOS: semanage port -​a -​t http_​port_​t -​p tcp PORT (service fails with Permission denied otherwise)
Domain not resolving dig example.​com +short and dig @8.​8.​8.​8 example.​com; record name typo (blog, not blog.example.com); dig NS example.​com — editing records at the wrong DNS host?; domain verified and not expired?; wait for TTL / flush local cache
Default site shows instead of your vhost server_name / ServerName + ServerAlias include the exact name?; Ubuntu: remove sites-​enabled/​default or a2dissite 000-​default.​conf; Nginx default_server elsewhere; inspect sudo nginx -T / sudo apachectl -​S; forgot reload?
Domain resolves but page times out Security group 80/443; DNS points to the right Elastic IP?; curl -​I http://​EIP -​H "Host: example.​com"