Quick Answer
When your Odoo server goes down, follow this triage protocol: 1) Check logs for 500 errors, 2) Verify service status with systemctl, 3) Test longpolling port 8072, 4) Monitor CPU/RAM with htop, 5) Check PostgreSQL connections. Most issues stem from bad custom modules, misconfigured workers, or database connection exhaustion.
Introduction: When Odoo Goes Dark
It's the call every IT Manager dreads. "Odoo is down."
When your ERP stops working, your business stops working. Warehouses can't ship, sales can't quote, and accountants can't bill. In these high-pressure moments, you don't need theories—you need a triage protocol.
Whether you are self-hosting on AWS/DigitalOcean or managing an Odoo.sh instance, the symptoms are often the same: 500 Internal Server Errors, infinite loading spinners, or complete connection timeouts.
This guide is your battle-tested checklist for identifying the root cause of Odoo server failure and restoring service fast.
Step 1: The "500 Internal Server Error" (The Generic Ghost)
Symptom: A white screen with a big 500 error, or a pop-up saying "The server encountered an error."
A 500 error means the server code crashed. This is almost always caused by a bad custom module or a Python dependency issue.
The Debugging Protocol: Reading Logs
Step 1: Check the Real Logs - The browser tells you nothing. You must SSH into your server and tail the live logs.
Command:
tail -f /var/log/odoo/odoo-server.logNote: Path varies by installation
Step 2: Trigger the Error - Reload the page that caused the crash
Step 3: Read the Traceback - Look for the line that says CRITICAL or ERROR
Clue #1: ImportError
You are missing a Python library
Clue #2: KeyError
A custom module is trying to access a field that doesn't exist
The Fix:
For Missing Libraries:
For Bad Modules:
Restart Odoo with the problematic module uninstalled or commented out in the addons path.
Step 2: Connection Refused / Website Down
Symptom: "This site can't be reached" (ERR_CONNECTION_REFUSED)
This means the Odoo service isn't running at all. It likely crashed and didn't restart.
The Debugging Protocol: Checking Service Status
Check Service Status:
sudo systemctl status odooIf it says "Inactive (Dead)" or "Failed":
Try to restart:
sudo systemctl restart odooIf it crashes immediately again: It's a configuration error. Check your odoo.conf file. Did someone change the db_password or xmlrpc_port?
Step 3: The "Longpolling" Disconnect (Chat & IoT Failure)
Symptom: The chat window keeps disconnecting, or the IoT box isn't responding.
Odoo uses a separate port (default: 8072) for "Live" features like Chat and Notifications. This is handled by a "Longpolling" process.
The Diagnosis: Reverse Proxy Misconfiguration
If you use a Reverse Proxy (Nginx/Apache), you likely forgot to forward the longpolling traffic.
Nginx Longpolling Config:
location /longpolling {
proxy_pass http://127.0.0.1:8072;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
}Ensure your Nginx config has a dedicated block for /longpolling
Step 4: Performance Bottlenecks (CPU vs. RAM)
Symptom: The site works, but it takes 10 seconds to load a page.
The Diagnosis: Worker Configuration
Run the htop command:
htopHigh CPU (100%)
You might have "Workers" configured incorrectly.
If you have 2 cores, do NOT set workers to 10. It will choke the CPU.
High RAM (Swap usage)
You are running too many workers for your memory size.
Step 5: Database "Zombie" Connections
Symptom: "FATAL: remaining connection slots are reserved for non-replication superuser roles."
This means PostgreSQL has run out of connections. Odoo (or a 3rd party script) opened hundreds of connections and never closed them.
The Fix:
Restart PostgreSQL:
sudo systemctl restart postgresqlPermanent Solution - Install PgBouncer:
For high-traffic systems, you must use a connection pooler like PgBouncer. It sits between Odoo and Postgres and recycles connections efficiently.
Troubleshooting Quick Reference
| Issue | Symptom | Quick Fix |
|---|---|---|
| 500 Error | White screen, server error popup | Check logs, fix missing Python libs |
| Connection Refused | Site can't be reached | systemctl restart odoo |
| Longpolling Down | Chat disconnects, IoT fails | Configure Nginx for port 8072 |
| Slow Performance | 10+ second page loads | Adjust workers, upgrade RAM |
| DB Connection Limit | FATAL: connection slots | Restart PostgreSQL, install PgBouncer |
Frequently Asked Questions
Where are Odoo logs located?
By default, on Linux systems, logs are at /var/log/odoo/odoo-server.log. On Odoo.sh, you can view them in the "Logs" tab of your branch dashboard.
How do I fix "XML-RPC Port is already in use"?
This means another instance of Odoo is already running. Run ps aux | grep odoo to find the rogue process ID (PID) and kill it using sudo kill -9 [PID].
Why does Odoo crash after restoring a database?
This is often a Filestore mismatch. The database contains links to images/attachments that don't exist in your new server's .local/share/Odoo/filestore folder. You must migrate both the database dump (.sql) and the filestore folder.
How many workers should I configure for Odoo?
Use the formula: Workers = (CPU Cores × 2) + 1. For a 4-core server, set workers to 9. Setting too many workers will choke your CPU and cause performance issues. Also ensure you have enough RAM (approximately 150-300MB per worker).
What is the difference between Odoo longpolling and regular HTTP?
Regular HTTP uses port 8069 for standard requests. Longpolling uses port 8072 for real-time features like chat, notifications, and IoT communication. Both ports must be properly configured in your reverse proxy (Nginx/Apache) for full functionality.
Conclusion: Proactive Monitoring is Key
Troubleshooting is necessary, but prevention is better. The most stable Odoo systems are those with automated monitoring (like Grafana or Zabbix) that alert you before the disk fills up or the CPU spikes.
Tired of Waking Up to Server Alerts?
Let Braincuber's DevOps team manage your infrastructure. We handle the backups, the security, and the 3 AM alarms so you don't have to.
Switch to Managed Odoo Hosting
Stable, secure, and scalable. Our DevOps team monitors your servers 24/7 so you can focus on growing your business.
24/7 monitoring • Automated backups • Security hardening