Odoo Major Version Upgrades: What Breaks in Custom Modules — Odoo & ERP article by Rui Codex

Custom modules most often break during an Odoo major upgrade because of changed ORM and API behaviour, renamed or removed fields, altered views and XML identifiers, and frontend or report changes. The safe approach is to inventory every custom addon, migrate it in a staging copy, and test complete business processes against recent production data before go-live.

Key takeaways

  • Custom modules usually break at the Python, view, data model and frontend layers, not in the business logic itself.
  • An inventory of every custom addon and its dependencies is the first deliverable of any upgrade project.
  • Migration scripts handle the standard changes, but they cannot judge the intent of your custom code.
  • Testing should cover end-to-end business processes and data reconciliation, not only whether the server starts.
  • A rollback plan and a rehearsed cutover reduce the risk of a failed go-live.

What breaks in custom modules during an upgrade?

Most breakage falls into a small number of categories. Custom code that touches the framework's internals is the most exposed, because the framework changes between major versions more than the business-facing features do. The exact list depends on your source and target versions, so check the release notes for both before you estimate effort.

Python code and the ORM

Custom methods that call framework APIs, override core methods or build queries by hand are the usual failure points. A method signature that worked in the old version may take different arguments in the new one, and a deprecated helper may be removed. Raw SQL is especially fragile because it bypasses the abstractions that the migration relies on.

Views, XML identifiers and data files

Views inherit from core views by external identifier. If a core view is restructured or renamed, your inheritance points at nothing, and the form may silently lose a field or fail to load. Data files that reference records by ID also need review, because identifiers that were stable in one version may not be in the next.

Frontend and reports

Custom JavaScript, web components and QWeb report templates depend on the frontend framework and the rendering engine. These layers often change more than the backend, so a module that looks fine in the backend can still break on the website, in the point of sale or in printed documents.

Tip: Treat views, reports and JavaScript as separate test targets. A green server start tells you nothing about whether a quotation PDF still renders correctly.

How do you inventory custom code before upgrading?

Build a complete list of every custom addon, every inherited core model and every external dependency before you touch the code. The inventory determines the effort estimate, the order of work and the test scope. Without it, teams discover breakage one module at a time after the deadline has already been set.

  • List each custom addon with its owner, purpose and the business process it supports.
  • Record every core model, method and view the addon overrides or inherits.
  • Flag raw SQL, direct file access, external API calls and scheduled actions.
  • Note third-party or community modules and check whether a version exists for the target release.
  • Mark modules that nobody uses any more, because retiring them removes work.

Once the list exists, sort the modules by business criticality and by how deeply they depend on core internals. Heavily customised modules that touch invoicing, stock valuation or payroll deserve the most attention, even if they are small.

Should you migrate custom modules or rewrite them?

Migrating an existing module is usually cheaper when its logic is sound and its dependencies are stable. Rewriting makes sense when the module works around a limitation that the new version solves natively, or when the original code is undocumented and fragile.

Each option fails in a different way. Migration carries forward design debt and hidden assumptions. A rewrite can drop edge-case behaviour that users depend on without anyone noticing until month-end. Whichever path you choose, record the expected behaviour before you change anything, so the tests have a reference to check against.

How do you test an upgraded Odoo system?

A usable test plan runs in layers, from fast automated checks to slow human validation. Start with automated tests for each custom module, then move to end-to-end process tests on a staging copy of the database. Finish with user acceptance testing for the processes that carry the most risk.

Layer 1: module tests and installation

Confirm that every custom module installs and upgrades on an empty database and on a copy of production data. Run the existing unit tests for the target version and write new ones for overridden methods. Installation errors are cheap to find here and expensive to find later.

Layer 2: business process tests

Script the processes that matter: order to invoice, purchase to payment, manufacturing order to stock move, and any integration that exchanges data with another system. Compare outputs with the results from the old system for the same inputs. Differences in totals, taxes, rounding or document numbering are the most important findings.

Layer 3: data reconciliation

After migration, reconcile record counts, balances and open items between the old and new databases. Check that custom fields hold the values they held before, and that computed fields recalculate correctly. Reconciliation catches silent data loss that functional tests can miss.

Layer 4: performance and integrations

Measure the slowest reports, list views and scheduled jobs on realistic data volumes. Verify every API integration with its real endpoints in a test environment, including authentication, error handling and retries. An integration that works with three test records can still time out under production load.

Tip: Keep the test scripts under version control and rerun the whole suite after every fix. A test you run once only proves the state of the code at that moment.

Hypothetical examples of upgrade failures

Here are two hypothetical scenarios:

In the first scenario, a custom sales module adds a discount field and overrides the invoice creation method. After the upgrade, the override still runs, but a core change to how invoice lines are created means the discount is applied twice on some orders. Functional tests on quotations pass, and only the invoice reconciliation test reveals the problem.

In the second scenario, a custom warehouse report uses a template that inherits a core report by identifier. The core template is restructured in the new version, and the inherited block no longer exists. The report still prints, but the custom column is missing. A visual check of the printed document in the process test would have caught it.

Both cases share a lesson: the failure appears in a process outcome, not in the module's own code, so tests need to check outcomes.

How do you cut over to the upgraded system safely?

A safe cutover rehearses the full sequence at least once on a copy of production, with timings recorded. The rehearsal shows how long the migration takes, which manual steps are needed and where it can fail. The live cutover should repeat only the steps that the rehearsal proved.

  • Freeze configuration and custom code changes before the final data copy.
  • Back up the production database and filestore, and verify that the backup restores.
  • Run the migration and the test suite in a fixed order, with sign-off at each stage.
  • Define in advance the conditions under which you roll back, and who decides.
  • Keep the old system available read-only for reference until reconciliation is complete.

The rollback plan matters as much as the forward plan. If you cannot return to the previous version within the agreed window, the cutover should be postponed rather than forced.

Rui Codex offers custom software development and system integration work, and Odoo projects can be scoped through the same engagement process. Published project examples are on the case studies page of the company site, and the broader Odoo and ERP guides cover related topics.

Frequently Asked Questions

Do all custom modules need to be rewritten for a major upgrade?

No. Many custom modules migrate with moderate changes to views, method signatures and data files. Rewriting is usually justified only when a module depends on internals that changed substantially, or when its original behaviour is poorly documented and cannot be verified.

How long should testing take before an upgrade?

Testing length depends on the number of custom modules, the number of critical processes and the quality of existing tests. Plan for several test cycles on a staging copy, and treat the schedule as dependent on how many defects each cycle finds rather than on a fixed number of days.

Can migration scripts handle custom code automatically?

Migration scripts handle standard framework changes, such as renamed fields or moved data, but they cannot judge what custom code is meant to do. Custom methods, overrides and reports still need manual review and functional testing after the scripts have run.

Should we upgrade customised Odoo systems on a fixed schedule?

Upgrade timing is a business decision about support, features and risk tolerance. Start planning early enough to inventory custom code and test it properly, and avoid scheduling a cutover close to a financial closing period.

Sources

Tags: Odoo Odoo upgrade custom modules software testing ERP migration regression testing API integration workflow automation

Need Help Implementing This?

Our team can help you put these insights into practice. From AI automation to custom software development, we build solutions that deliver real results.

Send a project request