Fix Joomla Upgrade Issues: 3.10 to 4, 5 and 6 Guide

Joomla upgrade issues are failures that show up when you change major version (3.10 to 4, 4.4 to 5, or 5.4 to 6), not ordinary patch updates. The usual causes are an extension or template still calling removed classes, PHP or the database below the target floor, a schema step that never ran, or the two Behaviour – Backward Compatibility plugins set the wrong way round on the 5.4 to 6 hop. A blank page after the files copy is a PHP fatal. Fix the fatal. Do not click update again.

Most upgrade guides repeat “back up, run Pre-Update Check, click update.” This one is built from the Joomla 6.1.0 source and the issue tracker: which plugin must be off and which on before Joomla 6 will even offer the update, what those plugins actually restore (441 legacy class aliases, and not JRequest), the SQL that gets you back into a locked administrator, the exact schema record to repair when Maintenance → Database is empty, and where the updater writes its log. If the updater cannot download the package at all, that is a different problem: how to update Joomla and fix update errors.

What you will learn

Which symptoms mean an extension, a template, PHP, the schema, or a compatibility plugin
The only safe hop order: 3.10 to 4.4, then 5.4, then 6, and why 6 refuses to start from anything else
Current PHP and database floors for Joomla 5 and 6
The two-plugin gate for Joomla 6 (compat off, compat6 on) and the SQL to undo a lockout
What Behaviour – Backward Compatibility 6 restores, measured from the plugin’s own class map
Joomla 6 API removals that break extensions, with the replacement for each
How to repair #__schemas when Maintenance → Database shows nothing to fix
How to reinstall core files without restoring a backup
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 and `administrator/logs/joomla_update.php`. Disable that extension. See the 500 guide if the log mentions rewrite
Class “JTable”, “JPlugin”, “JFactory”, or “JText” not found	Joomla 6: Behaviour – Backward Compatibility 6 disabled, or its Classes Aliases switch off. Joomla 5: Behaviour – Backward Compatibility disabled	Enable the plugin (SQL below if locked out), set Classes Aliases to Yes, then find the extension that still uses the alias
Class “JRequest” not found	Removed in Joomla 4. No compatibility plugin restores it	Replace JRequest with getInput()
Class “JoomlaCMSInputInput” or “JoomlaCMSFilesystemFile” not found	Moved out of core in Joomla 6	Enable Include Deprecated Classes in compat6, then port the extension to `JoomlaInput` and `JoomlaFilesystem`
Unknown column, or table does not exist	SQL schema step did not finish	System → Maintenance → Database → Update Structure
Maintenance → Database is empty and the update will not start	Missing row in `#__schemas`	Insert the row (Step 5)
Pre-Update Check says a plugin must be disabled	Joomla 5 compat plugin still on before the 6 hop	Disable it on 5.4, prove the site still works, then update
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
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
Article editor flickers in Firefox after 5.4.3 / 6.0.3	Firefox 148, not the upgrade	Hotfix or 5.4.4 / 6.0.4. See browser compatibility fixes
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.12	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 off, compat6 on	Joomla 6	Ignoring Pre-Update Check

Joomla 6 only installs from 5.4 because 5.4 is where the compat6 plugin is shipped and pre-enabled, and where the updater gained the two-plugin check (pull request 45493). Earlier 5.x releases do not have it. Joomla 3 reached end of life in August 2023. Planning notes from the project: Joomla 3 to 4 step-by-step migration and Joomla 5 to 6 planning. Our path write-up: Joomla 3 to 4, 5, and 6.

Server floors that cause upgrade issues

Use the current manual, not a 2023 table: 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 limits before the upgrade, not after a fatal: Joomla PHP.ini settings.

The Joomla 6 gate: two plugins, opposite settings

This is the part most guides get backwards. There are two plugins with almost the same name, and the updater checks both before it will offer Joomla 6 (the same check runs in php cli/joomla.php core:update):

Plugin	Element	Introduced	Purpose	Required state before 5.4 to 6
Behaviour – Backward Compatibility	`compat`	Joomla 5.0	Keeps Joomla 4 era code running on Joomla 5. Does not exist in Joomla 6	Disabled, and the site must still work with it off
Behaviour – Backward Compatibility 6	`compat6`	Joomla 5.4 (pre-enabled, inert on 5.x)	Keeps Joomla 5 era code running on Joomla 6	Enabled

The pre-update notice reads: “This plugin must be disabled and your site working correctly before updating.” The reasoning from the maintainers on issue #46299: if an extension still needs the Joomla 5 plugin, better that it fails on 5.4 where you can switch the plugin back on, than halfway through the 6 upgrade with a half-migrated database.

So the procedure is a test, not a checkbox:

On 5.4, disable Behaviour – Backward Compatibility (compat). Leave Backward Compatibility 6 enabled.
Click through the site and the administrator. If you get “Class JTable not found” or similar, an extension still depends on the Joomla 5 layer.
Re-enable compat to get the site back. If the administrator is dead, run this against the database (replace the prefix):
```
UPDATE jos_extensions SET enabled = 1
WHERE type = 'plugin' AND folder = 'behaviour' AND element = 'compat';
```
Find the extension. Search the plugins/, modules/, components/, and administrator/components/ folders for the class name in the error (for example JTable or JPlugin). A hit on JText inside the compat plugin itself is not your culprit.
Update, replace, or remove that extension. Disable compat again. When the site is clean with it off, take the backup and update to 6.

If you skipped the check (issue #46616) and landed on Joomla 6 with “Class JPlugin not found” on every page, the Joomla 5 plugin is gone; you cannot bring it back. Enable the 6 plugin instead:

UPDATE jos_extensions SET enabled = 1
WHERE type = 'plugin' AND folder = 'behaviour' AND element = 'compat6';

Then open the plugin in System → Plugins and confirm Classes Aliases is Yes. Extensions that needed the Joomla 5 plugin specifically will still fail and must be updated or removed. Settings detail: Behaviour – Backward Compatibility.

What Backward Compatibility 6 actually restores

We read the plugin shipped in Joomla 6.1.0 (plugins/behaviour/compat6). It has three switches:

Switch	Default on a fresh Joomla 6	What it loads	Errors it fixes
Classes Aliases	No (sites upgraded from 5.4 arrive with it on)	`classmap.php`: 450 aliases, 441 of them the old `J*` names (JFactory, JTable, JPlugin, JText, JHtml, JRoute…), plus `extensions.classmap.php` with 19 more	Class “JTable” / “JPlugin” / “JFactory” not found
Include Deprecated Classes	Yes	Maps `JoomlaCMS` onto the plugin’s `classes/` folder: CMS Filesystem (File, Folder, Path, Stream, Patcher), CMS Input (Input, Cookie, Files, Json), BaseApplication and the CLI application classes. Also defines `JPATH_PLATFORM`	Class “JoomlaCMSFilesystemFile” not found, “JoomlaCMSInputInput” not found, undefined constant JPATH_PLATFORM
Removed Assets	Yes	Empty stubs for four Web Asset Manager entries removed in 6 (`wcpolyfill`, `chosen`)	“Unsatisfied dependency” or unknown asset exceptions from extensions that still call Joomla 5 assets

For contrast, Joomla 3.10.12 shipped 377 aliases in libraries/classmap.php. Joomla 4 kept them in core, Joomla 5 moved them into the compat plugin, Joomla 6 moved them into compat6, and the project intends to delete them in Joomla 7. An extension that still says JFactory::getApplication() in 2026 is living on a plugin with a published end date. JRequest is not in any of these maps; it was removed outright in Joomla 4.

Joomla 6 removals that break extensions

From the official removed and backward-incompatible list, the items that produce real fatals on client sites:

Removed or changed	Symptom	Replacement
`JoomlaCMSInput*`	Class not found unless compat6 Include Deprecated Classes is on	`JoomlaInputInput` (drop-in)
`JoomlaCMSFilesystem*`	Same	`JoomlaFilesystemFile` and `Folder`; use `is_file()` / `is_dir()` instead of `File::exists()`
`BaseApplication`, `CliApplication`	Old `cli/*.php` scripts and cron jobs fatal	Console plugins on `ConsoleApplication`
`JPATH_PLATFORM`	`defined('JPATH_PLATFORM') or die` kills the file	`defined('_JEXEC') or die`
`getItem()` returns `stdClass`	Call to undefined method `get()` in overrides and plugins	`$item->title` instead of `$item->get('title')`
`Table::getInstance()` in core, `Table::addIncludePath()` no longer overrides	Custom table classes silently ignored	Instantiate the table class directly
`$app` in plugin layouts	Undefined variable in `plugins/*/tmpl` overrides	`$this->getApplication()`
`$this->db->getNullDate()` in view overrides	Undefined property `db`	Compare with `null`
`isCli()`	Call to undefined method	`$app instanceof ConsoleApplication`
Legacy `media/legacy/js` assets	Missing script errors	jQuery noConflict moved to `media/vendor/jquery/js`; compat6 stubs the rest

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.
Read the known issues page for the exact target release before you start, for example Joomla 6.0.3 known issues. A documented regression is not your bug to debug.

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 the updater’s own log at administrator/logs/joomla_update.php (the path follows Global Configuration → System → Path to Log Folder). Its last line tells you whether the run died during download, extraction, SQL, or cleanup.
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: Repair #__schemas when Database shows nothing

Some migration tools and hand-built databases leave #__schemas without a row for core. Maintenance → Database then lists nothing, and the updater refuses to run because it cannot tell which SQL files have been applied (issue #38594, procedure in Fix Database Table Structure NOT Up to Date).

In the database, find the extension_id of the row in #__extensions where name = 'files_joomla'.
List administrator/components/com_admin/sql/updates/mysql/ (or postgresql/) and take the highest file name. On Joomla 6.1.0 that is 6.1.0-2026-03-13.sql. Do not copy that value onto a different version; read your own folder.

Insert the row, with your prefix and your values:

INSERT INTO jos_schemas (extension_id, version_id)
VALUES (700, '6.1.0-2026-03-13');

Reload System → Maintenance → Database. Joomla now shows the core entry and probably some structure problems. Click Update Structure.

Step 6: Reinstall core files without a full restore

When the log shows the update died during extraction, half the core files are new and half are old. You do not need to roll back the database for that. System → Update → Joomla → Upload & Update accepts the full installation package of the version you are already on and re-copies every core file. Download the matching Full Package from the Joomla downloads page, upload it, and let it finish. Then run Step 4 once more.

Step 7: 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 reads the developer’s compatibility tag. It does not execute the code. The labels mean exactly this: “Compatible” is the developer’s claim, “Update Required” means a newer build declares the target version, “Missing Compatibility Tag” and “Update Information Unavailable” mean nobody has told Joomla anything. An extension can be green and still fatal on your overrides.

Step 8: 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. On the 6 hop, grep overrides for ->get(' on items, $this->db, and $app in plugin layouts (table above). Old overrides need a rewrite, not a file copy.
Put the real template back only after a full click-through.

Step 9: 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 10: Retest, then take the next hop

Homepage, login, one article, one contact or checkout, and the administrator, in Chrome and Firefox at least.
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. The Joomla Next channel will start announcing 7.x the same way it announced 6.

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.
Anything with cli/ scripts or cron: the CMS CLI application classes are gone in 6. Those jobs need console plugins or the compat6 Include Deprecated Classes switch until the vendor ships one.

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
Disabling the Joomla 5 compat plugin on 5.4 breaks the site and you cannot find which extension
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.

What thinner articles leave out

Topic	Typical post	This guide
Compatibility plugins	“Enable the compatibility plugin”	Two plugins, opposite required states, the updater code that checks them, and the recovery SQL for each
What compat restores	Not stated	Measured from Joomla 6.1.0: 441 J* aliases, CMS Filesystem and Input classes, four asset stubs, and the switch that defaults to No
JRequest	“Enable compatibility”	Removed in 4, restored by nothing, must be rewritten
Joomla 6 removals	Link to the manual	Ten items mapped to the fatal you will see and the one-line replacement
Schema	“Click Update Structure”	What to do when the Database page is empty, with the exact 6.1.0 SQL filename
Half-copied files	“Restore backup”	Upload & Update with the same version reinstalls core files
Logs	“Check the logs”	`administrator/logs/joomla_update.php` and what its last stage means
Pre-Update Check	Treated as a verdict	What each label actually means (developer metadata, not execution)

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. Joomla 6 only starts from 5.4.
Joomla 6 needs PHP 8.3 or newer. Joomla 5 needs PHP 8.1 or newer.
Before the 6 hop: Behaviour – Backward Compatibility off, Backward Compatibility 6 on, and the site working with that combination on 5.4.
Backward Compatibility 6 restores 441 legacy class aliases and the old Filesystem and Input classes. It does not restore JRequest, and Joomla 7 will remove it.
Read the first fatal and joomla_update.php. Disable that extension. Then fix schema, template, and .htaccess.
Empty Maintenance → Database means a missing #__schemas row, not a healthy site.
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 the two Behaviour – Backward Compatibility plugins set the wrong way round 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 and administrator/logs/joomla_update.php, 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. Joomla 6 is only offered from 5.4.

Which compatibility plugin must be on for Joomla 6?

Behaviour – Backward Compatibility 6 must be enabled. Behaviour – Backward Compatibility (the Joomla 5 one, no number) must be disabled and the site must work without it before you update.

The site broke after I disabled Backward Compatibility on 5.4. What now?

Re-enable it (from the plugin list, or with UPDATE on #__extensions where element = ‘compat’) and search your extensions for the class named in the error. Fix or remove that extension, then disable the plugin again.

I am on Joomla 6 and every page says Class JPlugin not found. How do I recover?

Enable Backward Compatibility 6 with UPDATE on #__extensions where element = ‘compat6’, then set its Classes Aliases option to Yes. Extensions that needed the Joomla 5 plugin itself must be updated or removed.

Does the backward compatibility plugin fix every old extension?

No. In Joomla 6.1.0 it restores 441 legacy class aliases, the old CMS Filesystem and Input classes, and four asset stubs. It does not restore JRequest or anything removed in Joomla 4.

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 that page is empty, insert the missing #__schemas row for files_joomla with the newest SQL file name from com_admin/sql/updates. If the administrator will not load, restore the backup.

Why do extensions break when Joomla itself updated cleanly?

Core files can be new while an extension still calls classes Joomla 6 moved or removed: CMS Input, CMS Filesystem, BaseApplication, JPATH_PLATFORM, or CMSObject getters. Update or replace that extension, or disable it until a compatible build exists.

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 Joomla Upgrade Issues (3.10 to 4, 5, and 6)