Common Errors by Service
This guide lists the most common errors and their solutions for each service.
Nginx
502 Bad Gateway
Cause: The backend (PHP-FPM, Node.js, etc.) is not responding.
# Check PHP-FPM
systemctl status php8.1-fpm
# Check logs
tail -50 /var/log/nginx/error.log
Solutions:
# Restart PHP-FPM
sudo systemctl restart php8.1-fpm
# Check the socket
ls -la /run/php/php8.1-fpm.sock
504 Gateway Timeout
Cause: The backend takes too long to respond.
Solutions:
# In nginx.conf or location block
proxy_connect_timeout 300;
proxy_send_timeout 300;
proxy_read_timeout 300;
# For PHP-FPM
fastcgi_read_timeout 300;
403 Forbidden
Cause: Permission or configuration issue.
# Check permissions
ls -la /var/www/html/
# Fix
sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 755 /var/www/html
Check Nginx config:
location / {
index index.html index.php;
try_files $uri $uri/ =404;
}
413 Request Entity Too Large
Cause: Uploaded file too large.
# In nginx.conf
client_max_body_size 100M;
Invalid Configuration
# Test configuration
sudo nginx -t
# See detailed error
sudo nginx -T
Apache
AH00558: Could not reliably determine the server's fully qualified domain name
sudo nano /etc/apache2/apache2.conf
Add:
ServerName localhost
AH01630: client denied by server configuration
Cause: Missing Require directive.
<Directory /var/www/html>
Require all granted
</Directory>
AH01071: Got error 'Primary script unknown'
Cause: PHP-FPM can't find the file.
# Check file exists
ls -la /var/www/html/index.php
# Check PHP-FPM config
cat /etc/php/8.1/fpm/pool.d/www.conf | grep "listen ="
PHP-FPM
Unable to open primary script
# Check permissions
sudo chown -R www-data:www-data /var/www/
# Check pool is listening
ss -ln | grep php
Max children reached
Cause: Too many simultaneous requests.
sudo nano /etc/php/8.1/fpm/pool.d/www.conf
pm = dynamic
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
Allowed memory size exhausted
sudo nano /etc/php/8.1/fpm/php.ini
memory_limit = 256M
sudo systemctl restart php8.1-fpm
MySQL / MariaDB
Access denied for user
# Connect as root
sudo mysql
# Create/modify user
ALTER USER 'user'@'localhost' IDENTIFIED BY 'new_password';
FLUSH PRIVILEGES;
Too many connections
# View current connections
sudo mysql -e "SHOW PROCESSLIST;"
# Kill sleeping connections
sudo mysql -e "SELECT CONCAT('KILL ', id, ';') FROM information_schema.processlist WHERE command = 'Sleep' AND time > 300;"
Increase limit:
sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf
max_connections = 200
Table is marked as crashed
# Repair a table
mysqlcheck -r database_name table_name -u root -p
# Repair all tables
mysqlcheck --repair --all-databases -u root -p
InnoDB: Unable to lock ./ibdata1
Cause: Multiple MySQL instances or crash.
# Check processes
ps aux | grep mysql
# Kill and restart properly
sudo systemctl stop mysql
sudo killall -9 mysqld
sudo systemctl start mysql
Can't connect to local MySQL server through socket
# Check MySQL is running
systemctl status mysql
# Check socket
ls -la /var/run/mysqld/mysqld.sock
# Restart
sudo systemctl restart mysql
Node.js
EADDRINUSE: address already in use
Cause: Port is already in use.
# Find the process
sudo lsof -i :3000
sudo ss -tlnp | grep 3000
# Kill the process
kill -9 PID
ENOMEM: not enough memory
Solutions:
# Increase swap
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# Limit Node RAM
node --max-old-space-size=512 app.js
EACCES: permission denied
# Avoid running as root
# Use port > 1024 or configure capabilities
sudo setcap 'cap_net_bind_service=+ep' $(which node)
Docker
Cannot connect to the Docker daemon
# Check service
sudo systemctl status docker
sudo systemctl start docker
# Check permissions
sudo usermod -aG docker $USER
# Log out and log back in
No space left on device
# Clean Docker
docker system prune -af
docker volume prune -f
# Check space
df -h
Container keeps restarting
# View logs
docker logs --tail 100 container_name
# Inspect
docker inspect container_name | grep -A 10 "State"
Port already allocated
# Find container using the port
docker ps | grep PORT
# Or find host process
sudo lsof -i :PORT
SSH
Connection refused
# Check service
sudo systemctl status sshd
# Check port
sudo ss -tlnp | grep ssh
# Check firewall
sudo ufw status
Permission denied (publickey)
# Check permissions
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
chmod 600 ~/.ssh/id_*
# Check owner
chown -R $USER:$USER ~/.ssh
Host key verification failed
# Remove old key
ssh-keygen -R SERVER_IP
Fail2ban
ERROR: NOK: ('sshd',)
# Check syntax
sudo fail2ban-client -d
# Check filters
sudo fail2ban-regex /var/log/auth.log /etc/fail2ban/filter.d/sshd.conf
Unable to find a corresponding IP address
# Check backend
sudo nano /etc/fail2ban/jail.local
[DEFAULT]
backend = systemd
# or
backend = auto
Let's Encrypt / Certbot
Challenge failed
# Check port 80 is open
sudo ufw allow 80/tcp
# Check .well-known is accessible
curl http://yourdomain.com/.well-known/acme-challenge/test
Nginx configuration:
location /.well-known/acme-challenge/ {
root /var/www/html;
}
Too many certificates already issued
Wait for rate limit to end (1 week) or use staging:
sudo certbot certonly --staging -d yourdomain.com
UFW Firewall
ERROR: Could not find a profile matching
# List available profiles
sudo ufw app list
# Use port directly
sudo ufw allow 22/tcp
# instead of
sudo ufw allow OpenSSH
UFW not blocking
# Check rule order
sudo ufw status numbered
# Rules are evaluated in order
# An allow rule first blocks subsequent deny rules
Universal Diagnostic Commands
# Recent system logs
sudo journalctl -xe
# Service logs
sudo journalctl -u service_name -n 100
# Last system errors
dmesg | tail -50
# All failed services
systemctl --failed
Tip
Always check logs first:
/var/log/syslog: System logs/var/log/nginx/error.log: Nginx/var/log/apache2/error.log: Apache/var/log/mysql/error.log: MySQLjournalctl -u service: systemd service