Joomla 6 backward compatibility plugin: test it switched off

The Joomla 6 backward compatibility plugin, “Behaviour - Backward Compatibility 6”, puts back code that Joomla 6 removed so older extensions keep working. It is switched off on a fresh Joomla 6 install and switched on for sites upgraded from Joomla 5.4. That split is why an extension can work on one Joomla 6 site and throw Class "JPlugin" not found on another. Test every extension with the plugin off, because that is the state Joomla 7 is expected to make permanent. You can spin up a Joomla 6 test site in about 30 seconds and run the check on a copy that does not matter.

What is the Joomla backward compatibility plugin?

It is a core plugin in the “behaviour” group that loads before other plugins and restores class names and classes the current Joomla version no longer ships. Joomla has used two of them. The first, “Behaviour - Backward Compatibility”, arrived in Joomla 5.0 and kept Joomla 4 extensions running. The second, “Behaviour - Backward Compatibility 6” (plg_behaviour_compat6), is the one that matters now.

The Joomla maintainers split them on purpose. In GitHub pull request #45336, merged on 14 May 2025, they created a new plugin with a new name. With two plugins, the updater can force the old one off before the upgrade and require the new one on. The official Joomla 6.0 and 5.4 release announcementof 14 October 2025 explains that in Joomla 5.4 the new plugin “does not perform any actions other than existing and being enabled.” It only starts doing work after the upgrade to 6.

The Joomla manual’s Compatibility Plugins page for the 5.4 to 6.0 migration states both rules: the old plugin “must be disabled before starting the upgrade”, and for the new one “it is mandatory that this plugin is both installed and enabled.” The Pre-Update Check in Joomla Update enforces both.

What does Backward Compatibility 6 restore?

The plugin has three jobs, and two of them are switches you can see in its settings. We read the plugin’s compat6.xml manifest in the Joomla 6.1 source on GitHub in September 2026 to confirm the options and their defaults:

The alias list is long. The plugin’s classmap.php file registers 450 class aliases by our count, most of them old J-prefixed names that Joomla has marked deprecated since 4.0. The manual’s Removed and Backward Incompatibility page for 5.4 to 6.0 lists what moved into the plugin and what is gone for good. The CMS Input namespace, for example, now lives only in the plugin. Separately, core models no longer return CMSObject; they return plain stdClass objects. That second change is not covered by the plugin at all: an extension that calls ->get('title') on a model result breaks with the plugin on or off.

Is the plugin on or off on your Joomla 6 site?

It depends on how the site reached Joomla 6. The Joomla 6.1 installer’s base.sql adds the plugin disabled, with Classes Aliases set to No, and marks it as locked, so it can be disabled but not uninstalled. The Joomla 5.4.0 update script dated 23 April 2025 adds it enabled, with Classes Aliases set to Yes. So a site upgraded from Joomla 5.4 keeps nearly every old class name, and a fresh Joomla 6 install keeps none of them.

In practice this produces a confusing pattern. A developer tests an extension on their upgraded Joomla 6 site, it works, and they ship it. A customer installs it on a brand new Joomla 6 site and gets a fatal error. Neither site is broken; they simply run with the plugin in different states. To check yours, open System → Manage → Plugins, set the type filter to behaviour, and look at the status of “Behaviour - Backward Compatibility 6”. Open it to see the two option switches.

Why does “Class JPlugin not found” appear?

The error means some extension still refers to a class by an old name that Joomla deprecated in 4.0, and nothing on the site defines that name any more. On Joomla 6, JPlugin exists only when Backward Compatibility 6 is enabled and its Classes Aliases option is Yes. Turn either one off and every extension that says extends JPlugin stops the page with An error has occurred. 0 Class "JPlugin" not found.

The same error shows up in several real situations. In GitHub issue #46299, opened on 16 October 2025, a site owner on Joomla 5.4 disabled the old compatibility plugin because the Pre-Update Check asked for it, and the whole site, front end and admin, stopped with Class "JTable" not found. They got it back by setting the plugin’s enabled column from 0 to 1 in the database. And in GitHub issue #46233, filed against Joomla 6.0 RC1 on 6 October 2025, system plugins loaded before the behaviour group. As a result, JPlugin failed even with the compatibility plugin on. That load-order bug was fixed on 7 October 2025, a week before 6.0.0 shipped.

The lesson from both: the error is a dependency you did not know about. The official Joomla 6.0 announcementsays “most extensions will work seamlessly” with the plugin enabled. “Most” is not all, and “enabled” is a state that is not expected to last past Joomla 6.

How do you test an extension with the plugin switched off?

Test on a site where breaking things costs nothing, and use the plugin’s off state as the baseline. A fresh Joomla 6.1 install is exactly that baseline, so there is nothing to switch before you start. Five steps cover it, and the same flow works for a template or a whole list of extensions:

1. Open a fresh Joomla 6.1 test site on PHP 8.3. Spin up a clean Joomla 6.1 site. A fresh install ships with Behaviour - Backward Compatibility 6 switched off, so you start in the strict state that Joomla 7 is expected to enforce.
2. Turn on maximum error reporting. In System, Global Configuration, open the Server tab and set Error Reporting to Maximum, then set Debug System to Yes on the System tab. A fatal error now shows the class name and a stack trace instead of a blank page.
3. Install the extension and use it. Upload the extension ZIP in System, Install, Extensions. Enable it, then open its admin screens and the front-end pages or modules it outputs. Save a form or a setting at least once.
4. Write down every error, then switch the plugin on. Note each error message. Then open System, Manage, Plugins, filter by the behaviour type, enable Behaviour - Backward Compatibility 6, set Classes Aliases to Yes, and repeat the same clicks.
5. Compare the two runs. If the errors disappear with the plugin on, the extension still depends on code Joomla 6 removed. It works today, but ask the developer for a native Joomla 6 version before Joomla 7.

Pick PHP 8.3 for the first run, the minimum that Joomla 6 accepts per our guide to Joomla system requirements, and repeat on PHP 8.4 if your host offers it. For the general method of vetting an unknown ZIP, see how to test a Joomla extension online, and for templates, how to test a Joomla template online. The step-by-step extension testing guide walks through the upload screens with the same kind of disposable site.

You can also get a first hint before you install anything. Unzip the extension and search its PHP files for extends JPlugin, JFactory::, JText:: and Joomla\CMS\Filesystem. Each hit is a line that needs the plugin. For example, a plugin class that starts with class PlgSystemSlider extends JPlugin will stop every page on a fresh Joomla 6 site. The search misses dynamic calls, so the click-through test above still decides.

What do the errors tell you?

Each failure points at a specific removed piece of code, so the message tells you which plugin option would hide it and how long that fix lasts. Run the test above and match what you see:

A “yes” in the last column is a reprieve, not a fix. The extension runs today because the plugin fills the gap, and it will stop running on the day the plugin goes away. Send the developer the exact error and the stack trace, and ask for a release that works with the plugin off. The Joomla manual’s list of removals in Joomla 6.0 names each change behind these errors, including the move away from CMSObject, so you can point them to the exact entry.

What if your site breaks after you turn the plugin off?

On a live site, turning the plugin off can lock you out of the administrator. The error fires on every page, the plugin manager included. The way back is the database. In phpMyAdmin or your host’s database tool, open the #__extensions table (with your real table prefix), find the row where element is compat6 and folder is behaviour, and set enabled to 1. That is the same recovery the site owner in issue #46299 used for the older plugin.

The simpler answer is to never flip the switch first on production. mySites.guru’s article “Joomla’s Compat Plugin Is a Crutch, Not a Fix”, updated on 28 August 2026, gives the same advice: disable the plugin on a staging copy, read the error logs, and only then touch the live site. The same article puts the class alias option of the older Joomla 5 plugin at “~500+ PHP function calls per request,” another reason not to leave it on longer than needed. On a throwaway test site a lockout is not even a problem; you close it and open another test site.

When will the compatibility plugin be removed?

Most likely in Joomla 7. The plugin’s own Compat6.php source filedescribes the aliases it loads as “deprecated since joomla 4.0” and “likely” to be removed in Joomla 7.0, and says the same of the legacy classes. The Joomla Software Release Cycleplans major versions for “October in a year with an odd year number,” which points to October 2027. The roadmap does not list a Joomla 7 date yet, so treat that as the expected window, not a fixed date.

Put the dates together and the timing is tight. Joomla 5 loses bugfix support on 13 October 2026 and security support on 12 October 2027, as our post on Joomla 5 end of life covers. A site that moves to Joomla 6 now and leans on the plugin could face its next forced change within a year. For the upgrade itself, follow the steps in how to upgrade Joomla 5 to 6, which include the plugin swap the Pre-Update Check asks for.

Conclusion

The Joomla 6 backward compatibility plugin is a bridge, not a fix. It restores 450 class aliases, the removed Filesystem and Input classes, and a few core assets, and it is on after a 5.4 upgrade but off on a fresh install. Test every extension and template with it switched off, read the errors, and ask for native Joomla 6 releases while there is still time before Joomla 7. The free Joomla test site guide covers every way to get a copy to test on, and the fastest is one click.

Frequently asked questions