Few Liferay projects go wrong in the application code. They go wrong at the database step: the upgrade runs for hours, stops on a cryptic stack trace, or finishes and leaves a server that will not start. If you are searching for a Liferay upgrade tool error, this guide covers how the Database Upgrade Tool works, how to read its output, and the failure patterns that come up most often, with an approach for each.
It builds on our guide to Liferay 7.4 end of support and upgrade paths. If you are still deciding where to upgrade, start there.
What the Database Upgrade Tool actually does
The Database Upgrade Tool is a standalone command-line program shipped in your Liferay bundle under tools/portal-tools-db-upgrade-client. It connects to a copy of your production database, runs the Liferay core upgrade processes and then the upgrade processes of every installed module, and writes the result back to the schema. It does not migrate your custom code, and the Document Library files are a separate workstream.
According to Liferay’s documentation, the script is called db_upgrade_client.sh (or .bat on Windows). Before Liferay 7.4 U82/GA82 it was named db_upgrade.sh, so older tutorials and forum threads use the old name. Since DXP 2025.Q3 the tool also runs verification checks before the upgrade starts, and if verification fails it stops before changing anything.
Before you run it: the setup mistakes that cause most failures
A large share of upgrade tool errors are configuration errors rather than genuine upgrade bugs. Check these first.
Wrong or missing configuration files
The tool reads the application server settings from app-server.properties and the database connection from a properties file. Liferay’s current reference says the older portal-upgrade-database.properties file is deprecated as of DXP 2026.Q1 and that database settings now belong in portal-upgrade-ext.properties; if the old file is present, the tool warns and ignores it. Check the reference page for your exact version. One community report describes the tool asking for the wrong database type, which usually means the configuration points at the wrong database or driver.
Running against production instead of a copy
Always upgrade a restored copy of production first. You need a realistic duration, you need to find data problems that only exist in real data, and you need a clean rollback path. Take a verified backup before every run. A rehearsal that fails on a copy costs nothing; the same failure on production costs a weekend.
Too little memory
The tool accepts JVM options with the -j option, for example -j "-Xmx8192m". Large databases with many documents, web content versions or assets can exhaust a default heap. If the log ends with an OutOfMemoryError, increase the heap and rerun from a fresh restore.
How to read the output before you panic
The tool writes to upgrade.log by default; you can change the file with the -l option. Do not stop at the last line on the console. Search the log for the first ERROR or exception, because later errors are often consequences of the first one.
Liferay also provides an upgrade report, an upgrade log context (enabled with upgrade.log.context.enabled=true in portal-upgrade-ext.properties) and MBeans for monitoring. Turn the report and the log context on for rehearsals; they make it much easier to see which module or step is slow or failing.
Common errors and how to approach them
1. A step that seems to hang for hours
Long-running steps are normal on big tables, but a genuinely stuck query is not. Liferay runs upgrade stall detection by default and logs whether a query appears to be waiting on a resource lock or is simply slow. If it is a lock, look for other sessions holding locks on the database, such as a running application server, a backup job or an open admin session. Make sure nothing else is connected to the schema during the upgrade.
2. A single module upgrade fails with an SQL or type error
Community threads show failures such as a PostgreSQL bigint = character varying type mismatch during a 7.0 to 7.4 upgrade. These usually point to inconsistent legacy data or a column type that drifted over the years. Read the stack trace to identify the failing upgrade step and table, inspect the offending rows, fix the data on the copy, and rerun from a fresh restore. Always keep the complete log; it is the first thing anyone helping you will ask for.
3. Verification blocks the upgrade (DXP 2025.Q3 and later)
Pre-upgrade verification is a safety net, so treat a failure as information first. Liferay documents two properties for the rare case where verification wrongly blocks a valid upgrade: upgrade.database.preupgrade.verify.enabled=false disables all verification, and upgrade.database.dl.storage.check.disabled=true skips only the Document Library checks. Use them as a last resort, once you understand why the check failed and have confirmed the data is fine.
4. The tool finishes but the server will not start
First confirm the log shows a successful completion. If not, treat the upgrade as incomplete. After starting the server, use the Gogo shell to review module upgrade status and re-run individual module upgrades; Liferay’s troubleshooting guide describes running upgrade modules one at a time from the Gogo shell to isolate the culprit. Also check that the connection details in the portal properties match the database you actually upgraded; one community report traced a failure to a malformed JDBC URL for SQL Server.
A rehearsal routine that prevents surprises
- Restore a fresh production copy and run the tool with the report and log context enabled.
- Keep the full
upgrade.logof every attempt, and note the duration per run. - Fix data problems on the copy, then repeat from a fresh restore so each run is clean.
- Run the Gogo shell upgrade checks after startup and confirm nothing is outstanding.
- Repeat the whole sequence at least once before the production window, and write the runbook from what actually happened.
This is the same discipline we apply on larger migrations such as our Liferay portal migration to DXP 7.4 case study. The tool rarely fails randomly; it fails on data and configuration that a rehearsal would have exposed.
When to bring in help
If your upgrade log shows repeated failures in core modules, if your database has years of legacy customisations, or if your maintenance window is tight, a technical assessment before the first run is cheaper than a failed one. Our Liferay services page explains how we approach upgrades end to end.
FAQ
Where is the Liferay database upgrade tool?
In your Liferay bundle under tools/portal-tools-db-upgrade-client. The script is db_upgrade_client.sh or .bat; before 7.4 U82/GA82 it was db_upgrade.sh.
How do I give the upgrade tool more memory?
Pass JVM options with the -j option, for example -j "-Xmx8192m", and size the heap to your database.
Can I skip the pre-upgrade verification?
On DXP 2025.Q3 and later you can disable it with upgrade.database.preupgrade.verify.enabled=false, but only after you understand why it failed. Fix the underlying data where possible.
Can I rerun the tool after a failed upgrade?
Restore a clean backup first and rerun from there. Running again on a half-upgraded schema can hide the original problem.
Planning a Liferay upgrade? Get a free technical assessment.