Troubleshooting Upgrades

Liferay has many out-of-the-box tools and features to identify and solve issues that may arise when performing an upgrade.

To troubleshoot, you can upgrade modules individually using Gogo shell commands to identify the source of any upgrade issues or to perform small upgrades while the server is running.

You can enable the upgrade report and upgrade logs or use MBeans to monitor and troubleshoot the upgrade process. Using these tools, you can find the sources of performance issues and the causes of any errors.

As of Liferay DXP 2025.Q3, the Database Upgrade Tool automatically runs verification processes before executing the upgrade. This causes the upgrade to fail before making any changes to the system.

Note

You can use portal properties to skip these verifications:

• upgrade.database.preupgrade.verify.enabled=false disables the verification process entirely. You can use this if the verifiers incorrectly block the upgrade.

• upgrade.database.dl.storage.check.disabled=true skips verfication checks specific to the document library. This property is included in the portal developer properties.

See Common Upgrade Issues for more information on troubleshooting.