Debugging Odoo is a skill that every Odoo developer, beginner or seasoned, needs in their toolkit. Whether you’re working on a minor customization or a complex enterprise-level solution, the ability to quickly pinpoint and resolve issues can dramatically improve the quality and reliability of your implementation.
Odoo is a powerful yet intricate platform. Thanks to its modular architecture, issues can surface in many different places, Python server logic, QWeb templates, PostgreSQL database queries, front-end JavaScript, or third-party API integrations. Without the right strategy, even a small bug can turn into hours of frustration.
In this blog, we’ll explore practical techniques, essential tools, and best practices that make debugging Odoo faster, more effective, and far less stressful.
1. Understanding the Odoo Debugging Modes
Debugging Odoo provides several built-in debug modes to help you analyze what’s happening behind the scenes.
Normal Debug Mode
You can quickly enable debug mode by adding ?debug=1 at the end of your Odoo URL. This gives you access to technical fields, view architecture, and developer tools directly from the user interface.
Example:
https://yourdomain.com/web?debug=1
Developer Mode (with Assets)
This mode loads JavaScript and CSS in unminified form, which is extremely helpful when you’re working on front-end customizations or fixing QWeb template rendering issues.
Activate it from the UI:
Settings → Activate Developer Mode
Developer Mode (with Assets and Tests)
This is the most comprehensive mode and is best used when you need to debug automated tests or deep front-end behaviors. It includes both unminified assets and testing tools.
You can switch between debug modes using the Developer Tools dropdown in the top-right corner of Odoo once any debug mode is active.
2. Using Odoo Logs Effectively
Logs are your first line of defence when something goes wrong.
Where to Find Them
Standard Installation:
/var/log/odoo/odoo-server.log
Docker Setup: Use this to view logs inside the container.
docker logs
Log Levels and How to Use Them
Odoo uses standard Python log levels:
INFO, DEBUG, WARNING, ERROR, and CRITICAL.
In development, setting the log level to DEBUG offers detailed insights:
log_level = debug
Update this in your odoo.conf file to capture more granular information, especially useful when tracing custom module issues or tracking database interactions.
3. Key Tools for Debugging Odoo
Several built-in and external tools can speed up the debugging process.
Browser Developer Tools
The browser’s Developer Tools (available in Chrome, Firefox, and Edge) help you inspect:
- HTML elements and QWeb output
- JavaScript console errors
- Network requests and API payloads
This is your go-to tool for front-end issues.
Odoo Shell (Odoo REPL):
Accessing the server shell with:
odoo shell or python3 odoo-bin shell
PostgreSQL Logs:
Enable query logging in PostgreSQL to understand slow or complex queries affecting performance. It’s beneficial when the ORM hides the underlying SQL’s real complexity.
PDB (Python Debugger):
Insert breakpoints in your code using:
import pdb; pdb.set_trace()
This halts execution and lets you step through your Python code to inspect variables and trace the problem.
4. Debugging Common Odoo Issues
Interpreting Python Tracebacks
When Debugging Odoo, a server error typically includes a stack trace. Learn to read this traceback line by line. The last few lines often indicate the function or model where the error originated, allowing you to quickly pinpoint the issue.
QWeb Template Errors
Issues with XML templates can break entire views. In Developer Mode, inspect views via the UI and use browser tools to trace broken templates or incorrectly referenced fields.
Access Rights and Record Rules
Misconfigured access control is a common problem. Use Developer Mode to:
- Check record rules and user roles
- View the effective permissions on models.
- Simulate user access with different roles.
External API Integration Failures
For APIs, the key to debugging odoo is isolation. Use tools like:
- Postman: Test your endpoints independently of Odoo.
- cURL: Lightweight CLI option for sending HTTP requests.
These help you separate the issue between Odoo code and the external service.
5. Recommended Debugging Addons and Modules
These community or built-in modules simplify your debugging workflow:
- web_debug: Easily toggle debug modes.
- auth_signup_disable: Quickly disable signup in staging environments for security.
- Odoo Studio: Use Odoo Studio to inspect models and fields visually.
These add-ons are handy during the development and testing phases.
6. Advanced Debugging Tips
When you’re dealing with performance bottlenecks or hard-to-replicate bugs, advanced methods can help.
Profiling Odoo Performance (using cProfile, Pyflame, or odoo-profiler).
These tools help identify slow functions or modules dragging down your performance.
Monitoring RPC calls
- (Especially in web apps and mobile).
For Debugging Odoo web clients or mobile apps, keep an eye on RPC (Remote Procedure Call) behavior. Use network tools to see:
- Request/response cycles
- Payload sizes
- Error messages
Testing with Odoo Unit Tests
- (writing and running tests to catch bugs early).
Odoo supports automated testing. Write tests using:
from odoo.tests.common import TransactionCase
Tests can catch logic errors early and provide confidence during code changes or upgrades.
7. Best Practices for Faster Debugging
Always Use a Staging Environment
Never debug directly on production. Create a clone of your production instance for testing. This protects data and prevents disruptions to real users.
Use Version Control Effectively
Work on feature branches in Git. This keeps experiments isolated and helps you roll back if needed.
Log and Document Known Issues
Maintain a shared log of recurring problems and their resolutions. It saves time in the long run, especially for teams.
Adopt Incremental Deployment
Deploy features in smaller chunks. It makes identifying the root cause of new bugs much easier.
Ready to Debug Smarter, Not Harder?
Debugging Odoo doesn’t have to be a guessing game. With the right mindset, tools, and habits, you can make it an efficient, even enjoyable part of your development workflow.
Start by enabling Developer Mode and reading logs to understand what’s happening under the hood. Use pdb and Odoo Shell for deep-dive investigations, while browser tools help you dissect front-end behavior. For performance tuning, profiling tools are your best bet, and when it comes to integrations, Postman or cURL can provide much-needed visibility.
Above all, make sure your debugging Odoo is safe, reproducible, and well-documented. The more you debug, the better you become – not just at fixing issues, but at preventing them.



