ERPNext: Resolving Internal Server Errors (HTTP 500) on ERPNext production sites

Before you start this troubleshooting, first log into your erpnext server and run cd ~/frappe-bench and proceed with the below instructions:

Step 1: Check Database (MariaDB) Status

The most common cause of a "500 Internal Server Error" in ERPNext is the database service being down or unresponsive.

1. Check Status:

sudo systemctl status mariadb

1. If the service is "Inactive" or "Failed": Restart it using:

sudo systemctl restart mariadb

1. Verification: Run the status command again. If it fails to start, check the logs for corruption or memory issues:

sudo tail -f /var/log/mysql/error.log

Step 2: Restart Supervisor (App Layer)

If MariaDB is active but the site still shows an error, the Supervisor (which manages the Python/Gunicorn processes) may have stalled or crashed.

1. Check Process Status:

sudo supervisorctl status

1. Ensure all processes (web, workers, schedule) are "RUNNING".
2. Restart Supervisor: If any process says "FATAL" or "BACKOFF," restart the entire group:

sudo supervisorctl restart all

Step 3: Restart Nginx (Web Server Layer)

Nginx acts as the reverse proxy. While it rarely causes a 500 error on its own (it usually throws a 502 or 504), a restart can clear stuck connections or configuration glitches.

1. Restart Nginx:

sudo systemctl restart nginx

Step 4: The "Full Refresh" Command

If individual restarts don't work, use the Bench CLI to clear the cache and reset the site environment. Run these commands from within your frappe-bench directory:

bench clear-cache
bench restart