How to know which custom Odoo addons will break when you upgrade

The first sign something is wrong

You click the upgrade button in your Odoo admin panel, the screen flashes, and then you see a red error message:

psycopg2.errors.UndefinedTable: relation "custom_module_name_some_table" does not exist

Or maybe the server simply refuses to start after the upgrade, printing a stack trace that ends with:

ValueError: Invalid field 'x_custom_field' on model 'product.template'

In both cases, the common thread is that a custom addon—something you or a vendor built specifically for your business—is no longer working the way it did before the upgrade. The symptoms are familiar to anyone who has run an Odoo upgrade: crashes on startup, database errors on access, or silent failures that only appear when users try to run a specific process.

This article shows you how to find out which custom addons will break before you upgrade, so you can decide whether to update the addon, remove it, or delay the upgrade altogether.

Why custom addons break during upgrades

What "custom addon compatibility" means

A custom addon is a module you (or a partner) wrote to extend Odoo’s standard features. It might add fields to existing models, create new reports, or change workflows. When Odoo releases a new version, its internal structure changes: field names move, database tables are renamed, and Python APIs are updated. If your custom addon refers to an old field or uses an old API call, it will fail when the new Odoo version loads it.

In Odoo terminology, this is called a breaking change. The Odoo core team publishes a list of breaking changes for each new version in the release notes. For example, in Odoo 16, the field product.template.x_custom_field was moved to product.template.x_new_field. Any custom addon that still uses x_custom_field will crash with the error shown above.

Where to find the breaking change list

Odoo publishes breaking changes in two places:

• CHANGES.rst in the Odoo GitHub repository (for the latest version)
• Odoo Developer Documentation under the Breaking changes section

If you are upgrading from Odoo 15 to 16, read the Odoo 16 breaking changes list. If you are upgrading to Odoo 17, read the Odoo 17 list. The lists are version-specific and do not apply to other versions.

Two kinds of breakage

Custom addons usually break in one of two ways:

• Startup breakage: The server fails to start because a Python class or field no longer exists. Example error: ImportError: cannot import name 'x_custom_model'
• Runtime breakage: The server starts, but crashes when a user tries to access a form or run a report. Example error: KeyError: 'x_custom_field'

Quick checks before you do anything else

Check your addon list

Before you begin, list all the custom addons installed in your Odoo instance. You can do this from the Odoo web interface or from the server command line.

Via the web interface (Odoo 15+):

1. Log in as an admin.
2. Go to Settings > Apps.
3. Click Update Apps List if the list looks stale.
4. Filter the list by typing custom in the search box.
5. Note the names of all custom addons. They usually start with custom_, l10n_custom_, or your company name.

Via the command line:

Run the following command from your Odoo server:

cd /odoo/custom/addons
ls -d */ | grep -v '^__' | sed 's|/||'

This lists all directories in /odoo/custom/addons that are not Python virtual environments. Each directory is a custom addon.

Check the addon manifest

Every Odoo addon has a manifest file named __manifest__.py. Open it in a text editor and look for the version field. Example:

{
    'name': 'Custom Product Labels',
    'version': '15.0.1.0.0',
    'summary': 'Print custom product labels',
    'depends': ['product'],
}

If the version field is missing or set to an old major version (e.g., 15.0.1.0.0 when upgrading to 16), the addon may not be compatible with the new Odoo version. This is a strong signal that you need to check the breaking changes list for that addon.

How to test each custom addon for compatibility

Step 1 – Create a staging copy of your database

Never test compatibility on your live database. Create a staging copy instead:

1. Back up your live database.
2. Restore the backup into a new Odoo instance with the target version (e.g., Odoo 16) on a staging server.
3. Install all custom addons in the staging instance.

If you do not have a staging server, you can use a local Docker container. See the Odoo integration guide for a simple Docker setup.

Step 2 – Start the staging server with the addon list

On the staging server, start Odoo with only one custom addon enabled at a time. This isolates breakage and makes it easier to identify which addon is causing the problem.

Use the --load flag to specify which addons to load:

./odoo-bin --config /etc/odoo/odoo.conf --database staging_db --load base,web,custom_product_labels

What success looks like: The server starts without errors and you can log in to the web interface.

What failure looks like: The server prints an error like ImportError: cannot import name 'x_custom_model' or KeyError: 'x_custom_field'.

Step 3 – Reproduce the user workflow

If the staging server starts, try to reproduce the user workflow that previously worked. For example:

• Open a product form and check if the custom field appears.
• Run the custom report or print action.
• Trigger the custom automation or scheduled action.

If any step fails with an error, note the exact error message and the addon that caused it.

Step 4 – Map the error to the breaking change list

Take the error message and search the breaking changes list for the Odoo version you are upgrading to. For example, if you are upgrading to Odoo 16 and see:

KeyError: 'x_custom_field'

Search the Odoo 16 breaking changes for x_custom_field. You might find:

• The field was renamed to x_new_field.
• The field was moved to a different model.
• The field was removed entirely.

This mapping tells you exactly what needs to be fixed in the custom addon.

Fix plan: decide what to do for each incompatible addon

Option 1 – Update the addon (best for critical addons)

If the addon is business-critical, assign a developer to update it for the new Odoo version. The developer should:

1. Check the breaking changes list for the target Odoo version.
2. Update the addon’s manifest version to the new major version (e.g., 16.0.1.0.0).
3. Fix any Python code that uses removed fields or APIs.
4. Update XML views to match new field names or model structures.
5. Test the addon in staging before deploying to production.

If you do not have in-house developers, contact the addon vendor for an updated version. Always check the vendor’s pricing page for upgrade costs before committing.

Option 2 – Remove the addon (best for non-critical addons)

If the addon is not critical, you can remove it from your instance before upgrading. This reduces risk and simplifies the upgrade process.

To remove an addon:

1. Uninstall the addon via the Odoo web interface (Settings > Apps > Uninstall).
2. Remove the addon directory from /odoo/custom/addons on the server.
3. Restart the Odoo server to confirm the addon is gone.

After removal, re-run the staging compatibility test to ensure the rest of your instance still works.

Option 3 – Delay the upgrade (best for incompatible critical addons)

If the addon is both critical and incompatible, and no update is available, delay the upgrade until the addon is updated. This is the safest option to avoid data loss or downtime. See the Odoo implementation guide for a phased upgrade strategy.

Documentation for developers

If you are assigning a developer to fix the addon, point them to the Odoo developer documentation on upgrading modules. The key steps are:

• Update the __manifest__.py version field.
• Use the _migrate_existing method to rename fields or tables.
• Test the migration on a staging copy before running it on production.

Verification checklist after fixing or removing addons

Pre-upgrade verification (staging only)

After fixing or removing each incompatible addon, re-run the staging compatibility test:

• Start the staging server with all remaining custom addons enabled.
• Log in and test the user workflows that were previously failing.
• Check the server logs for warnings or errors:

tail -n 100 /var/log/odoo/odoo-server.log | grep -i error

What success looks like: No errors in the logs, all user workflows work, and the server starts cleanly.

What failure looks like: Any error that mentions a custom addon, field, or model.

Production upgrade checklist

1. Backup your production database.
2. Stop the production Odoo server.
3. Run the upgrade on the restored backup in staging to confirm the fix.
4. Apply the same fixes to production.
5. Start the production server and monitor the logs for 30 minutes.
6. Ask a superuser to test the critical workflows in production.
7. If all is well, proceed with the rest of your upgrade plan.

Common pitfalls to avoid

• Skipping staging: Never upgrade production without testing in staging first.
• Mixing addons: Always test one addon at a time to isolate breakage.
• Ignoring dependencies: Some custom addons depend on other custom addons. If you remove one, the others may break.
• Forgetting scheduled actions: Custom scheduled actions often break after an upgrade. Check Settings > Technical > Scheduled Actions for any custom actions.

When to seek help

Triggers that mean you need help

If any of the following occur, stop and seek expert help before proceeding:

• The error message is unclear or does not match any breaking change in the list.
• You cannot reproduce the error in staging, but it occurs in production.
• The addon vendor is unresponsive or does not provide an upgrade path.
• The error involves a third-party integration (e.g., payment gateway, warehouse scanner) that is not an Odoo addon.
• The error persists after you applied all fixes and verified in staging.

Where to get help

If you need help, provide the following information to your Odoo partner or support team:

• The exact error message (copy and paste from the logs).
• The Odoo version you are upgrading from and to.
• The list of custom addons installed in your instance.
• The staging server URL and credentials (if available).
• A backup of the staging database.

If you are using an Odoo Enterprise subscription, log a ticket in the Odoo Support Portal. For community users, post the error on the Odoo Community Forum with the same details.

Bottom line: act before the upgrade, not after

Odoo upgrades are inevitable, but broken custom addons are not. By running a simple compatibility check in a staging environment, you can identify which addons will break and decide whether to update, remove, or delay the upgrade. The key steps are:

1. List all custom addons and check their manifests.
2. Create a staging copy of your database on the target Odoo version.
3. Enable one addon at a time and check for startup or runtime errors.
4. Map each error to the Odoo breaking changes list to find the fix.
5. Fix, remove, or delay each incompatible addon before upgrading production.

If you do nothing else today, take 30 minutes to list your custom addons and check their manifests. If any addon’s version field is behind the target Odoo version, flag it for review. That single action will save you hours of downtime and frustration when the upgrade day arrives.

For more on Odoo upgrades and custom addons, see the Odoo custom addons guide and the Odoo implementation guide.

Practical Next Step

Run the compatibility check today

FAQ