Fix Joomla Upgrade Issues (3 to 6)

Joomla upgrade issues are failures that show up when you change major version (3 to 4, 4 to 5, or 5 to 6), not ordinary patch updates. The usual causes are an extension or template still calling removed APIs, PHP or the database below the target version, a schema update that never finished, or a compatibility plugin left on the wrong setting. A blank page after the files copy is a PHP fatal. Fix the fatal. Do not click update again.

This is the Infyways map for those breaks on Joomla 4, 5, and 6. If the updater itself cannot download the ZIP, that is a different problem: use how to update Joomla and fix update errors.

What you will learn

Which symptoms mean an extension, a template, PHP, the schema, or the compatibility plugin
The only safe hop order: 3.10 to 4.4, then 5.4, then 6
Current PHP and database floors for Joomla 5 and Joomla 6
How to get the administrator back when you are locked out
When to stop and run the jump on staging instead of the live site

Issue map

What you see	Usual cause	Fix
White screen or 500 right after the upgrade	PHP fatal in an extension, template, or `.htaccess`	Read the host error log. Disable that extension. See the 500 guide if the log mentions rewrite
Class “JRequest” or “JFactory” not found	Joomla 3 API removed in Joomla 4+	Replace JRequest with getInput(). The compatibility plugin does not restore JRequest
Unknown column, or table does not exist	SQL schema step did not finish	System → Maintenance → Database → Update Structure
Next major never appears	Update channel still Default, or PHP too old	Joomla Next channel, then meet the PHP floor below
Site looks unstyled or modules vanish	Template or layout overrides built for Bootstrap 2 / Joomla 3	Switch to Cassiopeia to confirm, then update or replace the template
Pre-Update Check blocks Joomla 6	Behaviour – Backward Compatibility plugin, or server below Joomla 6	Set the compatibility plugin, then fix PHP and the database
Search or Weblinks menu errors	Those components left the core in Joomla 4	Use Smart Search. Install a maintained replacement only if you still need the old feature
Cart or catalog dies (VirtueMart, K2)	Extension build does not match the new major	Update that product to a build made for the target Joomla before go-live
Login loop after upgrade	Session table, cookie domain, or `$live_site`	Empty `#__session`, confirm the site URL in Global Configuration
Download failed, out of memory, stalled bar	Updater transport, not compatibility	Update-error runbook

Do not skip versions

You are on	Get current first	Next hop	Not this
Joomla 3.9 or older	3.10.x	Joomla 4.4	A direct jump to 5 or 6
Joomla 3.10	Extensions that have a Joomla 4 build	4.4 on staging	One-click on production
Joomla 4.0 to 4.3	4.4.x	Joomla 5	Joomla 6
Joomla 5.0 to 5.3	5.4.x	Joomla 6 only from 5.4	Skipping 5.4
Joomla 5.4	PHP 8.3+, supported database, compat plugin	Joomla 6	Ignoring Pre-Update Check

Joomla 3 reached end of life in August 2023. Planning notes from the project: Joomla 3 to 4 step-by-step migration. Our path write-up: Joomla 3 to 4, 5, and 6.

Server floors that cause upgrade issues

The 2023 requirements table (PHP 7.2, MySQL 5.6) is obsolete. Use the current manual: Joomla technical requirements.

Target	PHP	Database you should be on
Joomla 5	8.1 or newer. Prefer 8.2 or 8.3	MySQL 8.0.13+ or a current MariaDB. PostgreSQL 12+ if you use it
Joomla 6	8.3.0 minimum. 8.4 recommended	MySQL 8.0.13+ (8.4 recommended), MariaDB 10.6+ supported (10.4 is only the absolute floor), PostgreSQL 14+ supported

Joomla 6 also expects the PHP modules json, simplexml, dom, zlib, gd, and a database driver (mysqlnd, pdo_mysql, or pdo_pgsql). Recommended memory is at least 256M. Raise that before the upgrade, not after a fatal.

Step 1: Name the version hop

In the administrator, open System → System Information and note Joomla, PHP, and the database version.
Decide the single next hop from the table above. Do not chain 3 to 6 in one afternoon on the live site.
Take a restorable backup first. Method: how to backup a Joomla website.
Run that hop on a staging copy. Promote it only after the homepage, login, one form, and checkout (if any) work.

Step 2: Capture the real error

Turn on Joomla debug only on staging: Global Configuration → System → Debug System, and set Error Reporting to Maximum.
On production, leave display_errors off. Read the host PHP log and administrator/logs/.
Copy the first fatal line: class name, file path, and line number. Later fatals are often fallout.
If the log names .htaccess or mod_rewrite, stop and follow Joomla 500 on mod_rewrite.

Step 3: Fix PHP and the database before retrying

If System Information shows PHP below the floor for your target, the upgrade will fail or boot into fatals. Ask the host to switch PHP, then retest extensions on that PHP version before you change Joomla. A site that runs on PHP 8.0 cannot move to Joomla 6 until PHP is 8.3 or newer.

Same for MySQL 5.7 or a very old MariaDB. Move the database into the supported range, confirm utf8mb4, then upgrade Joomla.

Step 4: Repair the schema

If you can still open the administrator, go to System → Maintenance → Database.
Select the Joomla CMS entry (and any extension that shows problems).
Click Update Structure.
Reload the site. If the error was “unknown column” or “table doesn’t exist” and it is gone, you are done with this class of issue.

If the administrator will not load, restore the backup. Do not keep launching the updater on a half-migrated schema.

Step 5: Disable the extension that crashed

When the log names a file under /plugins/, /modules/, /components/, or /templates/ that is not Joomla core:

Prefer the administrator: System → Manage → Extensions, disable that extension, clear cache.
If you cannot log in, rename that extension folder over FTP or SFTP so Joomla stops loading it.
Or set enabled = 0 for that row in #__extensions. Match element and folder, not a guess.
Install a build made for the new major, or replace the extension. Re-enable only after that.

Pre-Update Check is metadata. It will not execute every code path. An extension can be listed as compatible and still fatal on your overrides.

Step 6: Repair the template and layout overrides

Joomla 4 replaced Bootstrap 2 and MooTools with Bootstrap 5 and Web Asset Manager. A Joomla 3 template, or a templates/YOUR_TEMPLATE/html/ override copied forward, will break layout, module chrome, or the whole page.

Set the site template to Cassiopeia (System → Site Templates). If the site renders, the CMS is fine and the old template is the issue.
Update the commercial template (Helix, T4, Gantry, and similar) to a release built for your Joomla major.
Diff layout overrides against the new core layouts. Old overrides that call removed classes need a rewrite, not a file copy.
Put the real template back only after a full click-through.

Step 7: Restore SEF without taking the site down

A major upgrade often rewrites .htaccess or leaves “Use URL Rewriting” on while the server still rejects Options or RewriteRule. Symptom: homepage maybe works, every other URL is a 500 or a 404.

Rename .htaccess to htaccess.bak so the site boots.
Turn off Use URL Rewriting until the new file is valid.
Rebuild from htaccess.txt using the mod_rewrite guide.
Confirm redirects you added by hand (www, HTTPS, old menu aliases) still exist. A fresh .htaccess drops them.

Step 8: Retest, then take the next hop

Homepage, login, one article, one contact or checkout, and the administrator.
System → Update → Extensions, so third-party code matches the new core.
Language packs. An English core with a stale translation can hide menu types.
Clear Joomla cache and any host or CDN cache.
Keep the pre-upgrade backup until the next business day.
Only then plan the following major, on staging again.

Removed APIs and the compatibility plugin

Joomla 4 deleted the Joomla 3 class layer: JRequest, JFactory, JError, and a long list of J* helpers. The System – Backward Compatibility plugin brings some of that back. It does not bring JRequest back. Code that still calls JRequest::getVar() must move to Factory::getApplication()->getInput().

The 5.4 to 6 hop adds another gate: Behaviour – Backward Compatibility. If that plugin is disabled or set to the wrong mode, Pre-Update Check blocks Joomla 6 even when PHP is fine. Settings and the safe order are in Behaviour – Backward Compatibility.

VirtueMart, K2, and page builders

These fail more often than core articles:

VirtueMart: install the VirtueMart build that declares your target Joomla major before you switch the core. A Joomla 3 cart on Joomla 5 will fatal in the shop, not in the updater.
K2: treat it as a migration. Many K2 sites need a content move, not an in-place upgrade.
Helix, SP Page Builder, Quix, Gantry: update the builder to the vendor release for that Joomla version, on staging, before the core hop.

When to stop clicking Update

Hire a staged upgrade if any of these are true:

You are still on Joomla 3 and the business cannot sit on a broken staging copy
Pre-Update Check lists extensions you cannot replace
Two attempts already left the schema or the administrator broken
Checkout, memberships, or a custom component is the revenue path

Infyways runs those jumps from $149, with a compatibility audit within 12 hours. Start at Joomla Upgrade Services.

Key takeaways

Upgrade issues are major-version breaks. Patch updates use the other guide.
Hop order is 3.10, then 4.4, then 5.4, then 6. No shortcuts.
Joomla 6 needs PHP 8.3 or newer. Joomla 5 needs PHP 8.1 or newer.
Read the first fatal. Disable that extension. Then fix schema, template, and .htaccess.
The compatibility plugin does not fix JRequest.
Prove the hop on staging. Keep the backup until the live site has been quiet for a day.

Frequently asked questions

What are the most common Joomla upgrade issues?

Incompatible extensions, old templates and layout overrides, PHP or database versions below the target, an unfinished database schema, and a mis-set compatibility plugin on the way to Joomla 6.

Why is my site blank after a Joomla upgrade?

A PHP fatal is hiding the page. Read the host error log, disable the extension or template named there, and do not run the updater again until the administrator loads.

Can I upgrade from Joomla 3 directly to Joomla 6?

No. Move 3.10 to 4.4, then to 5.4, then to 6, each hop tested on staging.

What PHP version do I need?

Joomla 5 needs PHP 8.1 or newer. Joomla 6 needs PHP 8.3.0 or newer, with 8.4 recommended. Details are in the Joomla technical requirements.

How do I fix database errors after upgrading?

Open System → Maintenance → Database and run Update Structure. If the administrator will not load, restore the backup instead of launching another update.

Why do extensions break when Joomla itself updated cleanly?

Core files can be new while an extension still calls Joomla 3 classes or old layouts. Update or replace that extension, or disable it until a compatible build exists.

Does the backward compatibility plugin fix every old extension?

No. It covers a limited set of legacy calls. It does not restore JRequest, and Joomla 6 will not start the upgrade until Behaviour – Backward Compatibility is configured.

Is it safe to upgrade the live site?

Patch updates are usually safe after a backup. Major upgrades should be proven on staging first.

Who can fix a broken Joomla upgrade?

Infyways handles failed upgrades and full version jumps. Request a Joomla upgrade audit.

How to Fix Common Joomla Upgrade Issues