Two changes landed in Odoo’s developer documentation this week that, individually, look like housekeeping. One fixes 54 broken links. The other swaps a single class name. But taken together, they mark the completion of two framework transitions that have been underway for months — and they carry real consequences for anyone building custom modules.
OWL v3 Breaks Every Documentation Link
Odoo’s frontend component system, OWL, has been the backbone of its JavaScript architecture since replacing the old Widget system. With the release of OWL v3, the project restructured its documentation on GitHub, moving all reference material from the top-level doc/reference/ directory into a versioneddoc/v2/reference/ path.
That single directory change broke every external link pointing to OWL documentation from Odoo’s own developer guides. And there were a lot of them — 54 across 11 files, touching everything from the framework overview to individual tutorials.
The Scope of the Fix
The affected files span the full breadth of Odoo’s developer documentation. The hooks reference alone had five broken links. The OWL components tutorial — the one most newcomers to Odoo development encounter first — had twenty-seven. Framework overview, web helpers, icon documentation, dashboard tutorials, view customization guides — all of them were sending developers to 404 pages.
The fix itself is mechanical: every instance ofowl/blob/master/doc/reference/ becomesowl/blob/master/doc/v2/reference/. But the fact that it took a second pass to catch links that used slightly different URL patterns suggests that the initial fix missed edge cases — a reminder that documentation link rot is harder to catch than code errors, because no compiler warns you when a URL stops resolving.
What OWL v3 Means for Odoo Developers
The version bump itself isn’t just a documentation reorganization. OWL v3 represents the framework’s continued maturation, with the versioned documentation path reflecting a more formal commitment to API stability and backward compatibility. By explicitly segregating v2 documentation under its own directory, the OWL team signals that future versions may coexist in the documentation structure — a pattern familiar from projects like React and Vue.
For module developers, the immediate action item is straightforward: if you’ve bookmarked OWL documentation links or referenced them in your own project wikis, update the paths. The old URLs return nothing.
Warning Is Gone From Server Actions
On the backend side, a smaller but more consequential change quietly landed: the Warning exception class has been removed from the server action evaluation context and replaced with UserError.
This matters because server actions are one of the most common ways Odoo administrators and integrators add custom logic without writing full modules. The evaluation context — the set of Python constructors and modules available inside a server action’s code block — determines what you can actually use. If your server actions raise Warning to display messages to users or halt execution, they need to be updated to UserError.
The change traces back to a core Odoo code modification that removedWarningfrom the action evaluation namespace entirely. It’s not deprecated with a fallback — it’s gone. Server actions that reference Warning will fail with aNameError at runtime, which in practice means they fail silently or break a workflow without an obvious error message for the end user.
The Migration Path
If you maintain custom server actions — and most Odoo deployments of any complexity do — the migration is a find-and-replace operation. Every instance of raise Warning(’message’) becomesraise UserError(’message’). The behavior is identical: the user sees a dialog with the message, and the current operation is rolled back.
The harder part is finding all the affected server actions. They live in the database, not in code files, which means grep won’t help. You’ll need to query the ir.actions.servermodel for any action whose code field contains the string Warning— a one-line domain filter in Odoo’s technical menu, but easy to overlook if you don’t know to look.
Two Sides of the Same Coin
These two changes — OWL v3’s documentation restructuring and the Warning-to-UserError swap — reflect the same underlying reality. Odoo’s developer platform is cleaning house. Framework APIs are being versioned and stabilized. Deprecated patterns are being removed rather than carried forward indefinitely. Documentation is being held to the same standard as code.
For the Odoo development community, this is ultimately good news. Cleaner APIs, versioned documentation, and explicit deprecation removals make the platform more predictable. But predictability requires paying attention to the transitions as they happen, not discovering them when a production server action throws a NameError at the worst possible moment.