On this page

Joomla Troubleshooting: Find and Fix Problems Step by Step

10 August 2026

Every Joomla site breaks eventually: a white screen after an update, a 500 error out of nowhere, a login that stops working, a change that refuses to show up. What separates a stressful afternoon from a five-minute fix is not luck - it is a method. Troubleshooting is a craft with rules, and Joomla gives you better tools for it than most people realise. And yes, sometimes that old "have you tried turning it off and on again?" joke is really the answer: a PHP restart genuinely cures a whole class of cache confusion.

This article is a systematic troubleshooting guide for Joomla. It covers the diagnostic method and first response for site owners, the classic failures - white screens, 500 errors, login problems, broken extensions, update trouble - with their fixes for administrators, and stack traces, bisection, and the command-line rescue kit for developers.

It builds on the Focus On articles about debug mode (the diagnostic instruments) and backups (your safety net); here we put them to work on a broken site. The patterns come from my many years of hands-on support on customers' sites and from moderating the Joomla forum and Stack Overflow, where thousands of broken-site threads follow the same handful of scripts.

A broken site is not a mystery. It is a machine with a fault, and faults can be found in order.

The goal is simple: help you go from "the site is broken" to "I know exactly what happened" - calmly, and in the right order.

1. The Basics

1.1 The Troubleshooting Mindset

Almost every Joomla failure follows one law: something changed. An update ran, an extension was installed, a setting was saved, the hosting provider upgraded PHP, a certificate expired. The first question is never "how do I fix this?" but "what changed since it last worked?". Answer that, and half your problems solve themselves.

1.2 The Three Rules

Reproduce first: make the problem happen on demand. A fault you can trigger is a fault you can trace.
One change at a time: change one thing, test, note the result. Five changes at once means you will not know which one fixed (or worsened) it.
Write it down: what you saw, what you tried, what happened. It stops you from going in circles, and it becomes the incident log the security article asks for.

1.3 Your Instrument Panel

Joomla and the browser already carry the diagnostic tools: the Debug System with its query and profiling console (the Focus On article about debug mode covers it in depth), the log files in administrator/logs (or your relocated log folder), the web server's error log, and the browser's developer tools (console and network tabs). The console also names JavaScript errors and mixed-content warnings - the classic flood after an HTTPS migration. Most of this article is knowing which instrument answers which question.

2. First Response: Triage

2.1 Narrow It Down in Four Questions

Where? Frontend, backend, or both? One page or all pages?
Who? All visitors, only logged-in users, only one account, only you?
When? Since when exactly - and what happened right before (update, install, save, host change)?
What exactly? A blank page, an error code, wrong output, or slow output? Copy the exact message.

These four answers cut the search space by ninety percent. "The site is broken" is unsolvable; "the frontend shows a 500 on all pages since the PHP update last night" is nearly solved.

One answer routes elsewhere: if the symptom is "slow" rather than "broken", switch to the measuring method in the Focus On article about performance - slowness is a performance problem with its own toolkit, not a fault to hunt.

2.2 Before You Touch Anything

Two disciplines from the backups article apply doubly on a broken site. First, take a backup now, broken as it is - if a repair attempt makes things worse, you can return to this state. Second, if you suspect a hack rather than a fault, stop and follow the incident response steps from the security hardening article instead: investigation comes before repair there, and repairs destroy evidence.

2.3 Buy Calm with the Offline Page

For a visibly broken public site, switch Site Offline on (Global Configuration, or php cli/joomla.php site:down). Joomla then serves the offline page with a proper 503 Service Temporarily Unavailable status - visitors see a tidy message and search engines know to come back later. Now you can work without an audience.

2.4 Asking for Help the Right Way

Sometimes the fastest fix is other people - the Joomla forum and Stack Overflow are full of them. Two habits decide whether you get an answer in an hour or never. First, search before you ask: paste the exact error message into the search box; at that scale, someone almost certainly hit your problem before you. Second, ask a question that can be answered. After years of moderating both platforms, I can tell you that the questions that get solved fast all share the same shape:

The exact Joomla and PHP versions, and the versions of the extensions involved.
The exact error message, copied - not paraphrased from memory.
What changed right before it broke (your section 2.1 answers).
What you already tried, and what happened when you tried it.
One problem per thread, with a title that names the symptom.

"My site is broken, please help!!" sits unanswered for days. "500 on all frontend pages since the PHP 8.3 upgrade, server log points at plugins/system/xyz" is often solved within the hour. The difference is not luck - the second question already contains the triage.

The Joomla forum has a tool that gathers most of this for you: the Forum Post Assistant (FPA). You upload one PHP script to your site's root, open it in the browser, and it produces a forum-ready report of your Joomla, PHP, database, and server configuration - which is why forum volunteers ask for an FPA report in most support threads. Do read it before posting and remove anything you consider private; the tool formats, but you stay responsible for what you publish. And it has a rewarding second use: read the report yourself first, and you will regularly spot the cause on your own - a wrong PHP version, a permissions problem, a configuration mismatch - and the question never needs asking at all.

3. Seeing the Real Error

3.1 Blank is Just Hidden

A production site correctly hides errors (the security article insists on it). But when troubleshooting, you need to see them. On a development copy - or briefly and deliberately on production - set Error Reporting to Maximum in Global Configuration → Server. The blank page becomes an error message with a file name and line number, and the hunt shortens dramatically.

3.2 When You Cannot Reach the Backend

If the backend itself is broken, set it in configuration.php directly:

public $error_reporting = 'maximum';

And if even that shows nothing, the error dies before Joomla starts - read the server logs instead: the PHP error log and the web server error log (locations vary per host; the hosting panel knows). The server log always has the real message, even when the browser shows pure white.

3.3 Reading an Error Message

Joomla and PHP errors follow a pattern: what went wrong (the exception or error type), where (file and line), and how it got there (the stack trace). The file path is the biggest clue: a path under plugins/system/somename/ points at that plugin; a path under templates/ points at the template or an override. You do not need to understand the code to identify the suspect.

4. The White Screen of Death

4.1 What It Is

A completely blank page means PHP stopped fatally before any output - and error display is off, so you see nothing. It is not a Joomla state; it is a hidden crash. The causes, in order of likelihood:

An extension incompatible with your PHP or Joomla version (often right after an update of either).
PHP memory exhausted (memory_limit).
A syntax error in a recently edited file - an override, configuration.php, a template edit.
A corrupted or half-finished update.

4.2 The Fix Sequence

Reveal the error (section 3). Nine times out of ten this alone names the file at fault.
If the file belongs to an extension: disable that extension (section 7) and retest.
If memory: raise memory_limit in PHP settings, then find out why it was exhausted - usually an extension in a loop.
If a recently edited file: restore it from backup or fix the syntax error at the reported line.

5. 500 Internal Server Error

5.1 The Server's "Something Broke"

A 500 is the web server reporting a failure it will not detail to visitors. The detail exists - in the server error log. Read it first; guessing at a 500 without the log wastes hours. The usual Joomla culprits:

Cause	Typical trigger	Fix
Broken `.htaccess`	Edits, moved site, options the host forbids	Rename `.htaccess` to test; rebuild from `htaccess.txt`, re-adding custom rules one by one.
PHP version switch	Host upgraded PHP; an extension is not ready	Check the log for the failing file; switch PHP back temporarily, update or disable the extension.
File permissions/ownership	Files moved or restored as the wrong user	Files 644, folders 755, owned by the PHP user - as in the security article.
mod_security rules	Saving content with code-like text	Ask the host to check the WAF log; whitelist the rule that fires.

5.2 The htaccess Halving Trick

When .htaccess is the suspect but the log is vague: temporarily comment out half the custom rules, test, then halve again. Four tests find the guilty line among dozens. This bisection pattern returns in section 11 for plugins - it is the universal troubleshooting move.

5.3 The Other Status Codes

The status code names the failing layer before you read a single log:

Code	What it tells you
`403`	Something refuses on purpose: file permissions, an IP block, a WAF rule, or a deny rule in `.htaccess`.
`404` on pages that exist	Routing: SEF settings, the rewrite block in `.htaccess`, or a menu change - the redirects article's territory.
`301`/`302` loop ("too many redirects")	Conflicting redirect rules: HTTPS forced in both Joomla and the server, or a CDN redirecting back.
`502` / `504`	The web server cannot reach PHP, or PHP takes too long: PHP-FPM crashed or is overloaded - the hosting layer, ask the host.
`503`	Joomla's offline mode - intentional (section 2.3), or a host maintenance page.

6.1 "Why Can't I Log In?"

Credentials: reset the password. Via mail, or when mail is broken, via CLI: php cli/joomla.php user:reset-password.
Account state: blocked, not activated, or forced to reset (the flags in #__users the authentication article describes).
MFA lockout: a lost second factor. Another Super User can reset the user's MFA methods on the user's account page.
Session/cookie trouble: the symptom is the login form returning silently, without an error message. See below.
Permissions: "an error has occurred" after a correct login often means the group lost its login permission - check core.login.admin / core.login.site in the ACL article's terms.

A login form that just reappears means the session cookie never sticks. The classic causes: a wrong cookie_domain or cookie_path in the Global Configuration (typically after a domain move - clear them), the browser blocking cookies, or a full/corrupted session table. Clearing #__session is harmless - everyone just logs in again.

6.3 Locked Out Completely

No working Super User at all? Two official escape hatches: the CLI can create or fix users (user:add, user:reset-password, user:addtogroup) without any web login, and the root_user emergency setting in configuration.php (described in the ACL article) can temporarily crown one account. Remove the latter as soon as you are back in.

7. Extension Emergencies

7.1 A Plugin Took the Site Down

System plugins run on every request, so a faulty one breaks everything - including your way to the plugin manager. Two clean rescues, no file hacking needed:

# The civilised way (works while the web is down):
php cli/joomla.php extension:list --type=plugin
php cli/joomla.php extension:disable <extension-id>

# The database way (phpMyAdmin or MySQL client):
UPDATE #__extensions SET enabled = 0
WHERE element = 'suspectname' AND type = 'plugin';

Then clear the cache and retest. If the site returns, you have your culprit - report it to the developer with your PHP and Joomla versions.

7.2 The Template Broke the Frontend

A fatal error in a template or its overrides blanks the frontend while the backend still works. Switch the default style to Cassiopeia in System → Site Template Styles (or set the home column in #__template_styles via the database if needed), fix the template on a copy, switch back.

7.3 Installations That Fail

"Unable to write" or silent failures during extension installs are almost always environment, not extension: a wrong or unwritable tmp_path in the Global Configuration, PHP upload limits (upload_max_filesize, post_max_size) below the package size, or disk quota. Fix the path, raise the limits, retry. A half-installed extension can be cleaned up with System → Discover or removed via extension:remove. A sibling limit worth knowing: max_input_vars caps the number of form fields per request, and saving a very large menu or module silently drops the surplus - raise it when big forms lose items on save.

8. Update Trouble

8.1 Broken Right After a Joomla Update

The post-update failure sequence, in order of success rate:

Clear every cache: Joomla's (System → Clear Cache or cache:clean), the browser's, any CDN's.
Delete administrator/cache/autoload_psr4.php. Joomla rebuilds this class-map cache on the next request; a stale one causes bizarre "class not found" errors after updates. This one file fixes more mysterious post-update breakage than anything else.
Run the database updater: System → Database → Update Structure (or php cli/joomla.php maintenance:database) to apply schema changes the updater may have skipped.
Suspect extensions: an extension incompatible with the new version shows up here first. Bisect (section 11.2), update or disable the offender.

8.2 When the Update Itself Died

An update that stalls midway (timeout, disk full) can leave a mixed installation. Do not run it again blindly: restore the pre-update backup (this exact scenario is why the update checklist in the backups article starts with one), fix the cause - usually PHP limits or disk space - and update again.

8.3 Extension Updates That Break Things

Same logic, smaller radius: clear caches, check the extension's changelog, roll back to the previous version if the developer offers it, or restore from backup. Then report - a well-written bug report with versions and the exact error helps the whole community.

9. Database and Content Issues

9.1 "Error Connecting to the Database"

Joomla cannot reach MySQL/MariaDB. Either the credentials changed (compare configuration.php against the hosting panel - typical after a migration), the database server is down or overloaded (ask the host), or the host changed the database hostname. The error appears before Joomla runs, so all fixes happen in configuration.php and the hosting panel.

9.2 Locked Content and Ghost Edits

"This item is being edited by another user" long after everyone went home means stale check-outs. System → Global Check-in frees them, and the globalcheckin task plugin (see the scheduler) prevents the recurrence.

9.3 After a Move: Missing Images, Wrong Paths

A restored or migrated site with intact text but broken images usually has absolute paths baked into content or configuration: check $tmp_path and $log_path in configuration.php (they must point at the new server's paths), and search content for hard-coded URLs of the old domain. The backups article's restore checklist covers the full sequence.

10. Cache and Session Confusion

10.1 "My Change Does Not Show Up"

The most reported non-problem in Joomla. Something is caching your old page; the question is which layer. Clear them in order, testing after each:

1. Joomla page/system cache   System > Clear Cache  (or: cache:clean)
2. Browser cache              hard reload / private window
3. CDN or proxy cache         purge in the CDN dashboard
4. OPcache (after file edits) restart PHP-FPM or ask the host

Test in a private window first - if the change shows there, the problem was your own browser all along, and the server needed nothing.

10.2 Sessions Behaving Strangely

Users randomly logged out, carts emptying, tokens rejected: session trouble. Check the session lifetime (too short?), the #__session table's health, and - after hosting changes - whether the session handler still matches what the server offers (a configured Redis handler with no Redis reachable fails exactly like this).

11. Under the Hood (Developer View)

11.1 Reading a Stack Trace Like a Map

A stack trace reads bottom-up as "how we got here" and top-down as "where it died". The top frame is the crash site, but the cause is usually the highest frame that belongs to third-party or custom code - core is rarely the culprit. Find the first non-core path in the trace and start there.

11.2 Bisection: the Universal Move

When nothing names a suspect, halve the possibilities: disable half the non-core plugins, test, halve again. Six tests handle sixty extensions. The same works for htaccess rules (section 5.2), template overrides (move half out of html/), and custom CSS/JS. Bisection feels slow and is almost always faster than intuition.

11.3 Comparing Against Clean

File-level doubts - "has something been modified?" - are settled by comparison, not memory: git diff if the site is in version control (the overrides article recommends it), or a download of the same Joomla version diffed against the installation. Modified core files mean either a hack (go to incident response) or a predecessor's shortcuts (document, then undo via proper overrides).

11.4 Write Your Own Trail

For intermittent faults, add temporary logging at the suspect spot:

use Joomla\CMS\Log\Log;

Log::add('Import reached step 3, id=' . $id, Log::DEBUG, 'com_example');

Entries land in the log folder and answer the question "does the code even get here?" - the question that ends most long debugging sessions. Remove the lines when done. And when logging is not enough - a value that changes somewhere across fifty function calls - a step debugger (Xdebug) pauses execution and lets you inspect variables live, which beats any amount of printed output.

12. The Command-Line Rescue Kit

Everything in this article assumed you might not have a working backend - because the CLI does not care whether the website renders. The rescue kit, all verified commands:

php cli/joomla.php site:down / site:up        offline mode toggle
php cli/joomla.php cache:clean                clear Joomla cache
php cli/joomla.php extension:list             find the extension id
php cli/joomla.php extension:disable <id>     kill the broken plugin
php cli/joomla.php extension:remove <id>      uninstall entirely
php cli/joomla.php user:reset-password        regain access
php cli/joomla.php user:add                   emergency admin account
php cli/joomla.php maintenance:database       fix schema after updates
php cli/joomla.php config:get                 read configuration values
php cli/joomla.php core:update:check          is an update available?

The Web Services API plays a smaller troubleshooting role - it needs a healthy Joomla to answer - but it shines for monitoring: an external script polling a lightweight endpoint notices the site is broken before your visitors email you. Pair it with an uptime monitor - for example the free, self-hosted Uptime Kuma from the maintenance checklist article - and "since when?" (section 2) always has an answer. If you maintain several sites, a central dashboard such as YourSites (covered in the security hardening article) adds a second diagnostic shortcut: when one site misbehaves, one glance tells you whether its siblings on the same server are fine - which separates a site problem from a server problem before you have opened a single log.

13. SEO and Metadata

How a site fails matters to search engines. Joomla's offline mode returns 503 Service Temporarily Unavailable - the status that tells crawlers "temporary, retry later" and protects your rankings during repairs. A site left broken with 500 errors or, worse, blank 200 OK pages teaches Google the pages are gone or empty, and recovery in the index takes far longer than the outage itself. So: visible breakage → offline mode on, fix, offline mode off.

After any outage or repair, give Search Console a look: crawl errors spike during incidents and confirm both the visitor impact and the recovery. And if the breakage involved redirects or moved URLs, re-test the redirect chains - the redirects article explains why broken chains quietly bleed ranking long after the site looks healthy again.

There is a tool for exactly this verification step. After a repair or migration, a site-wide crawl - Screaming Frog is the industry standard, and its free version crawls up to 500 URLs - finds in minutes what clicking around never will: broken links, redirect chains and loops, mixed content, and server errors on deep pages nobody visits. In my own support work, a post-repair crawl regularly surfaces two or three leftover problems on sites that looked fully healed - and every one found this way is one that Google and your visitors never meet.

14. Common Mistakes and Pitfalls

14.1 Changing Five Things at Once

Symptom: the site works again, but nobody knows why - until it breaks the same way next month.

Fix: one change, one test, one note. The discipline feels slow and is the fastest route there is.

14.2 Guessing at a 500 Without Reading the Log

Symptom: hours of trial and error while the exact error message sat in the server log the whole time.

Fix: logs first, always. The server error log for 500s, the PHP log for white screens, Joomla's logs for application errors.

14.3 Repairing Without a Backup of the Broken State

Symptom: a repair attempt made things worse, and now there is no way back to merely-broken.

Fix: back up first, even broken. Disk space is cheaper than regret.

14.4 Editing Core Files to "Fix" Something

Symptom: a quick patch in a core file solved the symptom - and dissolved at the next update, or broke it.

Fix: fixes belong in configuration, overrides, or the extension's own update. If a core edit seems like the only way, the actual bug belongs in a report to the Joomla project or the extension developer.

14.5 Leaving Diagnostics On

Symptom: weeks later, visitors see PHP notices and the debug console; error messages leak paths and queries.

Fix: error reporting Maximum and Debug System are surgical instruments - use, then switch off, as the security article insists. Put "revert diagnostics" on the same note you used for the fix.

14.6 Treating a Hack as a Fault

Symptom: strange files "fixed" by deletion, redirects "fixed" by editing htaccess - and back within days.

Fix: unexplained content changes, new admin users, or redirects to strange domains are incident response territory, not troubleshooting: contain, investigate, then restore, in that order (security article, section 10.4).

15. Best Practices

If you remember only a few things from this article, remember these:

Start with "what changed?", and answer "where, who, since when, what exactly" before touching anything.
Back up the broken state before repairing it; switch on the offline page (a real 503) for visible breakage.
Make the error visible before fixing it: error reporting, then the server logs - never guess at a 500.
Learn the four rescue moves: disable a plugin via CLI/database, switch to Cassiopeia, delete autoload_psr4.php, run the database updater.
Clear caches in order (Joomla, browser, CDN, OPcache) before declaring a change "not working".
Bisect when nothing names a suspect - halving beats intuition.
Keep the CLI rescue kit in your notes; it works when the web does not.
Stuck? Search for the exact error first, then ask on the forum with versions, the exact message, what changed, and what you tried.
One change at a time, notes always, diagnostics off afterwards.
If it smells like a hack, switch to incident response - do not "fix" evidence away.

16. Quick Reference

TRIAGE       what changed? where / who / since when / what exactly
             backup the broken state; site:down = proper 503

SEE ERRORS   Global Config > Error Reporting: Maximum (dev/briefly)
             no backend: $error_reporting = 'maximum'; in config
             still blank: PHP + web server error logs (hosting panel)

WHITE SCREEN reveal error > extension? disable > memory? raise+ask why
             > recent edit? restore/fix the reported line

500 ERROR    read the server error log FIRST
             .htaccess (rename to test, rebuild from htaccess.txt)
             PHP version switch / permissions 644-755 / mod_security
             codes: 403 perms/WAF - 404 routing - 30x loop redirects
                    502/504 PHP-FPM (host) - 503 offline mode

LOGIN        reset password (CLI: user:reset-password)
             account flags > MFA reset by other admin
             silent loop: cookie_domain/path empty, clear #__session
             locked out: user:add via CLI, root_user (remove after!)

EXTENSIONS   extension:list + extension:disable <id>
             or: UPDATE #__extensions SET enabled=0 WHERE element=...
             template broken: default style > Cassiopeia
             install fails: tmp_path, upload_max_filesize

UPDATES      clear caches > DELETE administrator/cache/autoload_psr4.php
             > System > Database > Update Structure > bisect extensions
             update died midway: restore pre-update backup

NOT SHOWING  private window first! then: Joomla cache > CDN > OPcache

DEV          stack trace: first non-core path = suspect
             bisect plugins/rules/overrides by halves
             git diff / compare against clean download
             Log::add() to trace intermittent faults

CLI KIT      site:down|up  cache:clean  extension:list|disable|remove
             user:reset-password  user:add  maintenance:database
             config:get  core:update:check

HELP         search the exact error first (forum.joomla.org, SO)
             ask with: versions, exact error text, what changed,
             what you tried - one problem per thread
             FPA report: upload script, run, review, post
             (often the report alone reveals the cause)

HACKED?      not troubleshooting - incident response:
             contain > investigate > eradicate > recover

17. Summary

Troubleshooting Joomla is a method, and the method survives every kind of breakage:

Triage: what changed, where, for whom, since when - plus a backup of the broken state and a proper 503 while you work.
Visibility: error reporting and the log files turn blank pages and 500s into file names and line numbers.
The classics: white screens (hidden PHP crashes), 500s (htaccess, PHP switches, permissions), login loops (cookies and sessions), each with a fixed diagnostic order.
The rescues: disable extensions via CLI or database, fall back to Cassiopeia, delete the autoload cache, run the database updater - four moves that resolve most emergencies.
The layers: cache confusion is solved in order, from private window to OPcache.
The craft: stack traces, bisection, comparing against clean, and temporary logging - the developer's four instruments for the stubborn ten percent.
The boundary: hacks are not faults; they get incident response, not fixes.

None of this requires genius - it requires calm, order, and knowing where Joomla keeps its answers. The panic version of troubleshooting changes random things until something helps; the method version reads the error, names the suspect, and fixes one thing. The second version is faster every single time.

And some faults resist even the method - the intermittent session bug, the conflict that only appears under load, the site that is slow for reasons three tools disagree about. Those are the puzzles where experience with hundreds of broken Joomla sites pays off, and exactly the kind of structured detective work a Joomla specialist enjoys: the harder the mystery, the more satisfying the one-line cause at the end.