The line number in a QWeb error is almost never where the problem is. The error class is almost never the full diagnosis. The stack trace will take you to Odoo's rendering engine, which is not where you made a mistake. QWeb error messages are written for the template engine, not for the developer trying to fix something at 4pm before a release.
This is a field guide to the five error shapes we see most often, what each one actually means, and where to look instead of where the error points you.
How QWeb rendering works (enough to make the errors readable)
QWeb is Odoo's XML-based template engine. It takes an XML template, walks the tree, evaluates Python expressions embedded in t-att-*, t-field, t-if, t-foreach, and other directives, and produces HTML. The rendering context is a Python dictionary. When an expression fails, QWeb throws from inside its own evaluation loop, which is why the stack trace almost always passes through ir.qweb or ir.qweb.field before you see anything about your template.
Two things to internalize before reading any QWeb error:
- The error location reported is where the renderer caught the failure, not necessarily where the bad code lives.
- The rendering context at the point of failure is everything. An expression that works in one context fails silently or loudly in another, depending on what is and isn't in the dictionary at that moment.
With that framing, the five patterns below become readable.
Pattern 1: Template not found
What the error says: Something like External ID not found or QWeb template not found, followed by a template name.
The misleading part: The error names the missing template. It does not tell you which template called it. You end up searching your codebase for the missing name and finding it, which makes you think the template exists and the error is wrong. It isn't wrong. The template exists in source, but it was not loaded into the database at the time of rendering.
The actual cause: One of three things, in order of frequency. First, the module containing the template was not updated after the XML was added or changed. The database has a stale version, or no version at all. Second, a t-call in one template references an external ID from a module that is not installed on this database. Third, a t-inherit was written against a template ID that has a typo, and the inheritance silently failed, leaving the original template in a broken state when the inherited version is later requested.
Where to look: Open developer mode and navigate to Settings, Technical, User Interface, Views. Search for the template ID exactly as it appears in the error. If it appears, the template is in the database. If it doesn't, the module needs an update (-u module_name on restart, or Update in the Apps interface). If it does appear but the error persists, the issue is a broken t-inherit chain: look for every view that has inherit_id pointing at this template and check their arch for syntax problems.
Pattern 2: Attribute access on None
What the error says: AttributeError: 'NoneType' object has no attribute 'some_field_name', or its Odoo ORM variant: AttributeError: 'bool' object has no attribute 'some_field_name'.
The misleading part: The field name in the error looks like a QWeb variable, and it is. But the stack trace points you into ir.qweb internals, and the expression that failed is shown as a string fragment with no surrounding context. You know what field was accessed on None. You don't know which record was None, or why.
The actual cause: A Many2one field that was not set, and the template assumed it was. The classic example is o.partner_id.street where partner_id is an empty Many2one. In Python this returns False, not None, which is why the error sometimes reads 'bool' object has no attribute. In the Odoo ORM, an unset Many2one is a falsy empty recordset, not None, but the effect is the same: chaining a field access on it fails.
Where to look: Find the expression in the template. Walk it left to right and identify every Many2one or relational access in the chain. Each one is a place where the record could be empty. The fix is usually a guard: t-if="o.partner_id" wrapping the block, or a safer expression like o.partner_id.street or ''. In report templates specifically, check whether the records passed to the report action can legally have unset relational fields, and add the guard at the template level rather than enforcing completeness at the data level. Both matter, but the template has to be defensive regardless.
Pattern 3: Infinite recursion in t-call
What the error says: RecursionError: maximum recursion depth exceeded, often with a stack trace that repeats the same frame dozens of times before truncating.
The misleading part: The repeated frame in the stack trace is deep inside the QWeb renderer, not inside your template. The frame that names your template appears once near the top and then disappears into the engine's loop. It looks like a renderer bug.
The actual cause: Template A calls template B with t-call, and template B calls template A, or template A calls itself. This happens most often when a t-inherit is used incorrectly: a template inherits itself (by referencing its own external ID in inherit_id and then calling the base in t-call), creating a cycle the renderer cannot escape. It also happens when two templates are refactored to share a common sub-template, and the refactor accidentally introduces a loop.
Where to look: Find every t-call in the template named near the top of the stack trace. For each called template, find every t-call inside it. You are looking for a cycle. In developer mode, the template viewer shows the full arch of each view: use it to read the call chain manually. For complex cases, a text search (project-wide find in your IDE, or grep -rn "t-call" . restricted to your custom module directories) across your templates listing all t-call values will let you draw the call graph on paper. The cycle will be visible.
Pattern 4: t-field on a non-existent or incompatible field
What the error says: ValueError: Unknown field "field_name" in "model.name", or a widget-related error like AttributeError thrown from inside an ir.qweb.field.* class.
The misleading part: t-field errors come from the field widget layer, one level above the core renderer. The error message names the field and the model, which looks helpful. What it doesn't tell you is whether the problem is a missing field, a field that exists but the widget doesn't support it, or a field that exists on a different model than the one the template is bound to.
The actual cause: Three sub-cases. First, the field was renamed or removed during a version upgrade and the template was not updated. Second, the template is bound to model A, but through a relational traversal it ends up calling t-field on a field that belongs to model B, and the widget resolves against the wrong model. Third, a custom ds_-prefixed field was added to a model and the module was not installed or updated on this database, so the field exists in source but not in the ORM registry yet.
Where to look: Confirm the field exists in the ORM by checking Settings, Technical, Database Structure, Fields. Filter by model name and search for the field. If it's there, the problem is the widget binding; check whether the t-field is being evaluated against the correct record type at that point in the template. If it's not there, the module needs an update. For version upgrades specifically, this pattern is worth a dedicated pass: any t-field reference in your custom templates should be checked against the new version's field list for the bound model before going live.
Pattern 5: Bootstrap markup conflicts
What the error says: Usually nothing, at first. The template renders without error. The output just looks wrong: columns collapse, spacing breaks, a section that worked in the backend report viewer is misaligned in the PDF output.
The misleading part: No Python error is thrown. This is not a rendering failure; it is a silent structural failure. The template is valid XML and valid HTML. The browser or PDF renderer just interprets it in a way you didn't intend.
The actual cause: QWeb report templates and website templates both use Bootstrap, but different versions and different compilation contexts. A grid structure that works in the website page editor uses classes that mean something different inside wkhtmltopdf's HTML renderer, which has its own Bootstrap interpretation. The common offenders are: nested .row elements without a containing .col-*, d-none classes that the PDF renderer doesn't apply because it doesn't run the same CSS, and container-fluid wrappers that add margin the PDF renderer doesn't strip.
Where to look: For PDF reports, render the template in a browser first by hitting the report URL directly with ?debug=1 appended. What you see in the browser is close to what wkhtmltopdf sees. Compare the computed widths. Then strip the Bootstrap grid from the problematic section and replace it with explicit table-based layout or inline widths, which are far more predictable in the PDF context. For website templates, use the browser's element inspector to find which Bootstrap class is colliding, and check whether the conflict came from a t-inherit that inserted a partial row structure into a template that already had its own grid.
The three tools worth knowing
The developer-mode template viewer. Settings, Technical, User Interface, Views. This is the authoritative version of every template in the database. The arch field shows the final merged result of all inheritance: not just your template, but every t-inherit that has been applied. When a template looks right in your source file but wrong at runtime, the viewer shows you the actual thing being rendered.
The rendering context inspection trick. In a custom module, temporarily override the template's rendering method and log the context dictionary before rendering. A single _logger.debug("QWeb context: %s", values) call before super() will show you exactly what variables are available in the template at runtime. This is the fastest way to confirm whether a None-access error is caused by a genuinely unset field or by a context variable that was never passed in the first place.
The AST inspection approach. For complex expressions inside t-if or t-att-* directives, paste the expression into a Python shell and evaluate it against a representative context dictionary. QWeb expressions are plain Python expressions evaluated with eval(). If the expression fails in a Python shell with the same context, you've isolated it without the renderer in the way.
QWeb errors become readable once you stop trusting the error location and start trusting the error pattern. The line number is noise. The error class is a starting point. The actual diagnosis is always about what was in the rendering context and whether the template structure matches it.
If QWeb errors are consuming more of your team's time than they should, that is usually a sign of one of two things: templates that were written without defensive guards, or a debugging workflow that hasn't been formalized. Both are fixable. DimeSoft audits custom Odoo templates and can help your team build a faster path from error to fix. A real conversation about what you're seeing is the right starting point. Reach out if that would help.