Upgrading from Joomla 3.10 to Joomla 4: A beginner’s checklist when extensions block the way

Quick overview: what upgrading from 3.10 to Joomla 4 means for site owners

Joomla 4 is a major release with architecture and API changes compared with the 3.x line. That means some templates and extensions written for 3.10 may need updates or replacements. Treat the upgrade as a platform migration rather than a simple patch: test first, and assume third-party code may require action.

Understand Joomla 4 compatibility signals (what warnings mean)

• Compatibility warnings in the Extension Manager or update screens indicate potential problems but do not always describe severity. Treat warnings as items that require investigation.
• Entries in the Joomla Extensions Directory (JED) or vendor release notes that list "Joomla 4" are useful signals, but still verify on a staging site before production upgrade.
• If an extension has no stated compatibility, flag it as unknown and test carefully or disable it during the upgrade.

What parts of your site are most at risk

• Third-party components (major functionality like e-commerce, directories, booking systems) and event-handling plugins are the highest risk.
• Templates and template overrides may require changes because of routing, CSS, or layout differences in Joomla 4.
• Custom or abandoned ("ghosted") extensions often create the most trouble if source code or vendor support is missing.

Practical example: Incompatible plugins can cause admin errors, broken frontend forms, or a server error (HTTP 500). Always assume a staging test is required.

Warnings: Do not upgrade production directly without a tested staging run. Changing PHP versions or core files can expose hidden issues — always have a full backup.

Pre-upgrade checklist: backups, staging, PHP, and system checks

Before touching the production site, perform these concrete preparation steps. Treat backups and a staging copy as mandatory.

Create a full backup: database + files

• File backup examples (via SSH): use zip or rsync to copy the site files. Example: zip -r site-files-backup.zip public_html/ (replace paths as appropriate).
• Database backup example (mysqldump): mysqldump -u dbuser -p dbname > site-backup.sql — replace credentials and database names. Verify exact flags and syntax for your DB engine before use.
• GUI option: Akeeba Backup is a popular Joomla tool to create self-contained site backups. If you choose a backup extension, read its restore documentation and test a restore on staging.
• Always test restoring the backup to a staging environment; an untested backup may be unusable when needed.

Setting up a staging copy (cPanel subdomain, local Docker, or VPS snapshot)

1. Copy files to a subdomain or separate server.
2. Export and import the database to the staging server, then update configuration.php to point to the staging DB and modify $live_site if used.
3. Protect the staging site from search engines and public access (HTTP auth or robots block).
4. If your hosting supports snapshots, take a snapshot before making changes so you can revert quickly.

Check and adjust PHP and database versions

• Switch PHP on staging to a version that meets Joomla 4 requirements for testing. Document current and target PHP versions.
• Confirm required PHP extensions are enabled (for example, mbstring, json, and others commonly required by Joomla).
• Record the current Joomla version, installed extensions and versions, the active template, and the current PHP version to aid rollback if needed.

Technical warnings: Never skip testing your backup. Do not run an upgrade on production while a backup or file copy is mid-process — this can create partial states.

How to audit your extensions and determine compatibility

An extensions audit turns unknowns into a clear action plan. Build a simple table and prioritise by business impact.

How to list installed extensions and capture their versions

• In Joomla admin: Extensions → Manage → Manage shows installed extensions. Use screenshots or export lists for a record.
• For larger sites you can query the extensions table in the database to extract names and versions — verify the exact SQL for your Joomla version before running queries.
• Include the active template and any custom plugins in your audit; they are part of the upgrade surface.

Where to check extension compatibility (JED, vendor site, changelogs)

• Search the Joomla Extensions Directory for compatibility flags and version notes.
• Visit vendor websites, GitHub repositories, and changelogs to locate Joomla 4 support information.
• If no information exists, mark the extension as unknown and plan to disable it in staging for testing.

Actions per-extension: update, disable, uninstall, replace, or keep-as-is

• If the vendor provides a Joomla 4 update → plan a staged update and test it there first.
• If source is available but no update → consider porting the extension via a developer.
• If critical functionality has no update and no source code → find a replacement or hire a developer. If non-critical, consider removal to reduce long-term maintenance risk.

Sample audit table row (plain text example):

Warnings: Disabling an extension can remove functionality or affect data flows. Uninstalling may delete tables or stored data — check vendor documentation and back up before uninstalling.

Handling custom or 'ghosted' extensions: repair, replace, or remove?

Custom extensions left by a previous developer ("ghosted") require careful handling. Use a conservative process: disable, test, and then decide.

How to safely disable and test custom extensions

• Disable the extension via Extensions → Manage → Manage and then run key workflow tests (forms, login, checkout, front-end pages).
• Keep a copy of extension files and DB tables before uninstalling anything.
• Record errors after disabling to see which site parts relied on the extension.

When to replace vs port vs remove

• Replace: when a supported alternative exists in JED that meets your needs.
• Port: when you have source code and a developer can update it for Joomla 4.
• Remove: when functionality is non-essential and removal reduces future risk and maintenance burden.

Practical example: An "AddToMenu" plugin written for 3.x might duplicate functionality available in later Joomla releases. Before removing such a plugin, verify whether core Joomla 4 now includes the needed behavior and test recreating the menu items on staging.

Warnings: Do not delete custom files or DB tables until you are certain they are not needed. Custom extensions may create or modify database structures used elsewhere on the site.

Step-by-step upgrade on a staging site (safe runbook)

Run the upgrade on staging first using a clear runbook. This section gives a practical sequence to follow.

Runbook (high level)

1. Ensure a tested backup and/or host snapshot is available.
2. Put the staging site into maintenance mode.
3. Switch PHP on staging to a Joomla 4-compatible version for testing.
4. Disable non-essential third-party plugins and modules (capture pre-upgrade state).
5. Run the Joomla core upgrade (built-in updater or manual package).
6. Re-enable extensions in small groups, testing after each group.
7. Run full functional and visual checks; collect logs and errors.

Using Joomla’s built-in updater vs manual package upgrade

• The built-in updater is the standard path and is usually the easiest for typical installations. Read the official upgrade notes first.
• Manual package upgrades (uploading the Joomla 4 install package via Extension Manager or replacing files) can be useful in controlled environments but require care with file permissions and missing files.
• Always follow official Joomla migration guidance; verify these steps with the Joomla project documentation before performing the upgrade on production.

Testing sequence: enable, test, re-enable

• After core upgrade, enable extensions in small logical groups so you can isolate the one that causes errors.
• Test key user journeys after each re-enable: admin login, front-end rendering, contact forms, and any e-commerce flows.
• Keep a log of backend logs, PHP error logs, and Joomla logs to speed troubleshooting.

Commands and examples (staging-only):

• Switch PHP via hosting panel: typically done in cPanel or through your hosting control panel; steps vary by host — consult your host docs.
• Enable error reporting temporarily in configuration.php for staging (remember to disable on production after debugging). Always follow documented, safe methods for changing configuration.

Warnings: Enable debug only on staging. Upgrading with active incompatible extensions can cause fatal errors; be prepared to disable recently enabled extensions quickly if the site becomes inaccessible.

If the automated upgrade fails: troubleshooting and rollback options

If things go wrong, the primary recovery method is to restore from a known-good backup or host snapshot. This section explains common diagnostics and rollback approaches.

Safe rollback: how to restore from backup or snapshot

• Restore files and the database from the backup you made before upgrading. If you used a host snapshot, use the host's snapshot restore feature.
• If you used a backup extension like Akeeba, follow its documented restore process and test the restored site on staging.
• After restore, test site functionality thoroughly before attempting another upgrade run.

Common post-upgrade diagnostic steps

• Check PHP error logs and Joomla logs (logs folder) for stack traces and error messages.
• Enable debug and error reporting on staging to capture detailed errors (then disable after fixing).
• Identify the offending extension by disabling groups of recently re-enabled extensions and retesting.

Practical example: A PHP fatal error trace often contains the plugin or class name that failed. Use that clue to locate and disable the offending extension or to supply detail to a developer.

Warnings: Restoring files without matching DB state creates inconsistencies. Do not reuse an unverified or corrupted backup.

Post-upgrade checklist: test list, cleanup, and performance checks

After a successful upgrade on staging (and again after production upgrade), run these checks to stabilise and optimise your site.

Checklist for SEO and functionality verification after upgrade

• Functional checks: admin login, content editing, contact forms, scheduled tasks and any e-commerce checkout flows.
• Visual checks: template layout, responsive behaviour, menu displays, and media assets.
• SEO checks: verify SEF URLs and routing, robots.txt, sitemap, and meta tags. Run a quick site crawl to detect broken links.

Performance and security checks

• Re-enable caches and test page load times. Monitor for regressions against baseline metrics.
• Verify admin area permissions, update any changed credentials, and disable debug logging on production.
• Check PHP Opcache and other server-side performance settings.

Warnings: Do not re-index production search engines before confirming URLs are stable. Do not leave debug logging enabled on production.

When to get professional help and what to ask a developer

Some upgrades exceed a site owner's comfort or time. Knowing what to include in a developer brief speeds resolution and improves quotes.

How to prepare a useful support request

• Provide: staging URL, temporary admin credentials (change passwords after work), a read-only backup link, and the extensions audit table.
• Attach error logs and exact steps to reproduce issues, plus a short list of "must work" features (login, shop, forms).
• Ask for a fixed-price quote for scoped tasks (e.g., port plugin X to Joomla 4) and an hourly rate for open-ended debugging.

Typical time and cost signals

• Small fixes (template CSS, minor config) may take a few hours; porting a custom extension or resolving database schema problems can take days.
• Ask for milestones and acceptance tests so you know when the work is complete.

Warnings: Do not share permanent production admin credentials. Use temporary accounts and change passwords after work is finished. Get a written scope and testing plan before authorising major changes.

FAQ

Will the upgrade to Joomla 4 automatically break my site if some extensions are incompatible?

Incompatible extensions can cause functionality loss or errors. The safe approach is to back up, test on staging, and disable unknown or incompatible extensions before upgrading. Whether Joomla blocks the upgrade or automatically disables incompatible extensions should be verified against the official Joomla migration documentation; do not rely on assumptions for production upgrades.

How do I find which extensions/plugins/components/modules will work in Joomla 4?

Create an audit: list installed extensions, check the Joomla Extensions Directory compatibility flags, vendor sites, and changelogs. Flag unknown items for staging tests. For large sites, export lists from Extension Manager or query the extension table (verify SQL queries before running them).

What preparatory steps should I take before attempting the upgrade?

Make full backups (files and DB), create a staging copy, confirm server meets Joomla 4 requirements (PHP and DB versions), and record the extension inventory. Test restoring backups and switching PHP versions on staging.

Can I run an automatic upgrade and roll back if something goes wrong?

You can run the built-in updater on staging; rollback is typically done by restoring backups or using a host snapshot. Ensure backups are tested and available. Verify rollback behavior and exact commands against your backup tool's documentation (for example, Akeeba backup instructions).

What if a third-party extension has no Joomla 4 update and the original developer disappeared?

Options include: find a replacement in JED, search for community forks or GitHub copies, hire a developer to port the extension (if source is available), or remove the extension if the functionality is non-critical. Always disable and test before removing to avoid data loss.

When should I remove an extension versus replace or update it?

Decide based on business impact, availability of updates/source, security risks, and maintenance cost. Critical features with no updates often need replacement or developer help; non-critical ones can often be removed to reduce long-term risk.

What post-upgrade checks are essential?

Test core workflows (login, forms, purchases), verify templates and menus, regenerate caches and sitemaps, check SEO routing and structured data, and monitor performance. Disable debug and verbose logging on production after testing.

When is it time to hire a developer?

Hire help if core functionality breaks, custom extensions need porting, database schema errors appear, or you lack reliable backups. Provide a clear brief with staging access, logs, and the extensions audit to get accurate quotes.

Conclusion

Upgrading from Joomla 3.10 to Joomla 4 when extensions block the way is manageable with a methodical approach: backup first, stage the site, audit extensions, decide per-extension actions, run a controlled upgrade on staging, and follow a focused post-upgrade checklist. When in doubt, collect logs and create a clear developer brief. Verify technical steps against official Joomla documentation before making production changes.