How to Debug Server Errors in Odoo On-Premise

When you have Odoo deployed on your infrastructure, you have complete control over your deployment. You are also responsible for any server-side issues that may happen. This is different from Odoo Online or Odoo.sh, where Odoo S.A. handles a lot of the infrastructure. With an On-Premise deployment, your team needs to be able to handle any issues that may happen at all levels of the stack.

There are reasons why server errors can happen in an Odoo On-Premise deployment. These include settings, database connection issues, Python dependency issues, or even permission issues. This article will cover some of the common types of server errors, how to find the right log to diagnose the issue, and a step-by-step solution to resolve them.

Understanding the Odoo Server Architecture

Before we start debugging, it is useful to know the components of an Odoo On-Premise solution and where possible issues can be located. An Odoo On-Premise solution can be divided into the following layers:

• Odoo Application Server: This is the Python-based application that runs all business logic and provides access to the web interface.
• PostgreSQL Database: This is where all data is stored, including configuration, transactions, and users.
• Nginx or Apache (Reverse Proxy Server): This is used for all HTTP/HTTPS traffic that is routed to the Odoo application server.
• File System: This is where all attachments, sessions, logs, and addons are stored.
• Operating System: This is usually Ubuntu or Debian, which manages all system resources, users, and process execution.

A mistake in any of these layers may result in a symptom that manifests in a layer. For example, a database connection error may manifest as a "500 Internal Server Error" in the browser. Knowing this structure helps us identify the source of a problem, rather than focusing on the symptoms.

Accessing and Reading Odoo Log Files

The important tool in debugging server-related issues is the Odoo log file. The log file contains all the application-level activities, such as the startup of the application any warnings that might occur during the process, and any Python or database query-related issues. Understanding the location and content of the log file is the starting point for debugging.

Default Log File Location

The default log file location varies depending on the installation mode. In On-Premise installations, the log file is located in one of the following paths:

/var/log/odoo/odoo-server.log
/var/log/odoo/odoo.log
~/.odoo/odoo-server.log

The default log file location varies depending on the installation mode. In most On-Premise installations, the log file is located in one of the following paths:

Reading the Log in Real Time

When actively debugging an issue, it is recommended that you monitor the log file in real time. This is because you will be able to see the error messages that occur when you reproduce the issue in the browser. To do that, you should use the following command:

sudo tail -f /var/log/odoo/odoo-server.log

To filter the output and show error-level entries pipe the output through grep:

sudo tail -f /var/log/odoo/odoo-server.log | grep -i 'error\|critical\|traceback'

Understanding Log Levels

Odoo has various levels of log entries. Understanding the levels of log entries helps in prioritizing the log entries that need immediate attention:

• DEBUG: Detailed diagnostic information. It is usually used during development.
• INFO: General information confirming that the system is functioning as expected.
• WARNING: Indicates that there is a problem but the system is functioning.
• ERROR: Indicates that there was a failure in the execution of the system. The system is running, but the operation failed.
• CRITICAL: Indicates that there was a failure that might prevent the Odoo service from running.

Common Server Errors and How to Debug Them

The sections describe some of the most common server errors encountered in the deployment of the Odoo On-Premise system, their causes, and how they are resolved.

1. Odoo Service Fails to Start

The debilitating error is when the Odoo service is unable to start at all. This error is usually indicated by the absence of any response in the browser. This error may also be indicated by the error "connection refused." This error is resolved by checking the service's status and logs immediately after trying to start the Odoo service.

sudo systemctl status odoo
sudo journalctl -u odoo -n 100 --no-pager

Common reasons for startup failure include:

• Incorrect database credentials in the Odoo configuration file (odoo.conf).
• A port conflict in which another process is already using port 8069.
• Missing or incompatible Python dependencies.
• Incorrect file permissions in the Odoo addons directory or log directory.
• A syntax error or import error in your own module.

To check for port conflicts, you can use the following command and check if the port 8069 is not in use:

sudo ss -tlnp | grep 8069

2. Internal Server Error (HTTP 500)

If there is an HTTP 500 error, it means that there was an unhandled exception raised by the Odoo application server. This is one of the common errors, and in most cases will have a traceback in the Odoo log file.

To get the traceback, you can search for the word Traceback or ERROR around the time of the error in the log file:

grep -n 'Traceback\|ERROR' /var/log/odoo/odoo-server.log | tail -50

The traceback will display the exact Python file, line number, and type of exception that caused the error. Some common causes of this error are problems with the code in the custom module, missing database columns because the module has not been fully upgraded, or trying to call a method on a None object. The last line of the traceback is the most specific error message.

If the error is caused by an incomplete module upgrade, the following command should be entered to upgrade the module and rebuild the schema:

sudo -u odoo odoo -c /etc/odoo/odoo.conf -u module_name -d your_database --stop-after-init

3. Database Connection Errors

Database connection errors manifest themselves when the Odoo application server is not able to connect or maintain a connection to the PostgreSQL database. The error is normally visible in the log file in the form of messages containing keywords such as OperationalError, could not connect to server, or FATAL: password authentication failed.

To confirm whether PostgreSQL is running and accessible, the following commands should be executed:

sudo systemctl status postgresql
sudo -u postgres psql -c '\l'

If the PostgreSQL database is running but the Odoo instance is unable to connect to the database, the database credentials in the Odoo configuration file should be verified. The database host, database port, database user, and database password in the odoo.conf file should be verified against the actual PostgreSQL database role and authentication methods.

The PostgreSQL pg_hba.conf file should also be verified to allow the Odoo system user to connect to the database. The PostgreSQL service should be reloaded after making changes to the pg_hba.conf file:

sudo systemctl reload postgresql

4. Permission and File System Errors

Permission errors occur when the Odoo process does not have the required read or write permissions for the files or directories that it needs. Permission errors are often seen when Odoo tries to write the log files, store attachments, or load any custom addons.

Commonly seen permission error messages are as follows:

PermissionError: [Errno 13] Permission denied or IOError: [Errno 13]

To resolve permission errors, the directories need to be owned by the Odoo system user:

sudo chown -R odoo:odoo /var/log/odoo/
sudo chown -R odoo:odoo /var/lib/odoo/
sudo chown -R odoo:odoo /opt/odoo/custom/addons/

For the addons directory, it is also important to ensure that Python files are readable and that the addons directory itself is executable by the Odoo user:

sudo chmod -R 755 /opt/odoo/custom/addons/

5. Memory and Performance Errors

On heavily loaded servers or servers with insufficient RAM, Odoo may experience memory-related errors, such as MemoryError or be terminated by the Linux OOM (Out of Memory) Killer. These errors may also manifest as extremely slow response times or service crashes.

To verify if the OOM Killer has killed the Odoo process, the kernel message log can be used. 

sudo dmesg | grep -i 'oom\|killed'

To monitor the memory usage of the running Odoo process in real time, the following command can be used:

watch -n 2 'ps aux | grep odoo'

If the memory is consistently low, the RAM of the server can be increased or the number of running Odoo worker processes in the odoo.conf file can be reduced. The ideal values for the workers parameter in the odoo.conf file can be obtained by calculating the value with the formula: workers = (CPU cores * 2 + 1).

Quick Reference: Common Errors at a Glance

The table below is a quick reference guide for the most commonly experienced Odoo On-Premise server errors, along with their primary solution paths:

Enabling Debug Mode in Odoo

Odoo provides a feature known as “debug mode,” which provides additional technical information in the user interface. Using “debug mode” may be beneficial in troubleshooting particular views, fields, or workflows.

Activating Debug Mode via URL

The easiest way to turn debug mode on is to add ?debug=1 to the URL in your browser. For example:

http://your-odoo-server:8069/web?debug=1

To turn debug mode on and enable assets logging, which is useful for front-end debugging, you can use:

http://your-odoo-server:8069/web?debug=assets

Activating Debug Mode via Settings

Additionally, debug mode can be activated through the Odoo user interface by clicking Settings, then General Settings, and then scrolling to the Developer Tools section. One then clicks on Activate the developer mode to activate it. This mode is persistent for the user.

Debugging Custom Module Errors

Custom modules are one of the most common sources of errors in Odoo On-Premise solutions. Errors may happen during the installation, upgrade, or execution of the custom module. Below are the steps to follow when debugging the custom module error.

• Step 1: Check the Odoo log file for a Python traceback right after the error happened. The module name, file, and line number should be indicated in the traceback.
• Step 2: Ensure the module manifest file (__manifest__.py) is correctly formatted and that all dependencies are installed and up to date.
• Step 3: If the error is related to a module upgrade, run the upgrade command in the terminal to see the output without log file truncation.
• Step 4: Utilize the debug mode of Odoo to examine data in fields, view technical information of data in views, and test server actions.
• Step 5: If the problem is related to the database schema, check whether previous migrations left behind columns or constraints using a PostgreSQL client.

When performing a command-line update of a custom module, it is always a good idea to test against a copy of the live database before making any irreversible schema changes:

sudo -u odoo odoo -c /etc/odoo/odoo.conf -u your_custom_module -d test_database --stop-after-init

Best Practices for Ongoing Error Prevention

Proactive measures can help prevent server errors from occurring as often or being as severe in an Odoo On-Premise environment. The following best practice recommendations are applicable to all production environments:

• Schedule database backup jobs for your PostgreSQL database using pg_dump and store them on a separate server or cloud storage.
• Implement automated log rotation for your server using logrotate to avoid disk space usage issues.
• Use tools such as htop, netdata, or prometheus along with Grafana to monitor your server's resource usage.
• Test all your module code and Odoo version updates in a staging environment before deploying them to your production environment.
• Keep your operating system, PostgreSQL, and Python packages up to date to the latest versions to avoid security and compatibility problems.
• Document your Odoo configuration, module code, and any system-level customizations to help you debug your code and recover from disasters.

To debug server errors in Odoo On-Premise, one should adopt a systematic approach that involves reading the log files, pinpointing the level of the error, and making targeted corrections. The most productive debugging sessions involve real-time log file monitoring, Odoo’s native debug mode, and an in-depth knowledge of the underlying server architecture.

Regardless of whether the problem is related to the startup of the server, the inability to connect to the database, or a Python stack trace from a custom module, the problem resolution process follows the same basic steps: replicate the problem, read the log files, pinpoint the root cause of the problem, and make targeted corrections in a controlled environment before pushing the corrections to production.

Investing in log file configuration, server monitoring, and a well-configured staging environment will greatly minimize the time and effort required to resolve server errors and make your Odoo On-Premise system more stable and reliable.

To read more about Overview of Debugging in Odoo 19, refer to our blog Overview of Debugging in Odoo 19.