Debug in Joomla

2. Turning Debug On

2.1 The Debug Settings Tab

On System → Global Configuration → System you find the Debug Settings group with three fields:

Set Debug System to Yes, click Save, and reload a page. The console appears - provided the plugin is enabled and you are allowed to see it (section 6).

2.2 Error Reporting Goes With Debug

Debug Mode shows PHP warnings, but PHP only generates them if error reporting allows it. The related field sits one tab over, on System → Global Configuration → Server:

When you are chasing a hard problem, set Error Reporting to Maximum together with Debug System. You then see every notice PHP can raise. Set it back to System Default (or None) before you go live, so visitors never see a raw PHP error.

2.3 What Happens the Moment Debug Turns On

Switching debug on changes more than the console. Joomla also:

• defines the JDEBUG constant as true, which the whole CMS checks (section 7);
• starts the application Profiler, so timing marks are recorded;
• turns GZIP compression off for the request, so the console HTML is not compressed away.

This is why a debug page can look and behave slightly differently from a normal one. Debug Mode is a diagnostic state, not a transparent overlay.

4. Reading the Debug Console

Each tab in the console is filled by one data collector. Knowing what each one means turns the bar from noise into a map of the request.

4.1 The Queries Tab Is Where Speed Problems Hide

The Queries tab counts every query and shows its duration. Two patterns reveal trouble at a glance:

• A high total count (hundreds of queries on one page) usually means an extension is querying inside a loop. This is the classic "N+1" problem.
• One slow query standing out from the rest points to a missing index or a heavy join.

The same query repeated many times is also flagged, which quickly exposes code that asks the database for the same thing again and again instead of caching it.

As a loose rule of thumb, a normal Joomla page runs under about a hundred queries; a few hundred is a sign to investigate, and several hundred almost always means an extension is looping. These are not hard limits - a complex page legitimately needs more - but a sudden jump in the count is a reliable warning sign.

4.2 The Profile Tab Reads Like a Timeline

The Profile tab lists named marks from the start of the request to the end - "afterInitialise", "afterRoute", "afterDispatch", "afterRender", and more. The time between two marks tells you which phase is slow. A big jump before "afterRender" points at the template or modules; a jump around "afterDispatch" points at the component doing the work.

4.3 Query Traces: Find Out Who Fired a Query

Knowing a query is slow is only half the answer; you also need to know which extension issued it. Turn on the Query Traces option (section 5.1) and each query in the Queries tab gains a call stack - the chain of files and methods that led to it, for example a module helper calling loadObjectList(). This is what turns "120 identical category queries" into "this module is querying inside a loop", because the trace names the file and line responsible. It is the fastest way to pin a query on the extension that owns it.

6. Controlling Who Sees Debug

6.1 The Allowed Groups Option

By default, when Debug System is on, everyone who visits the site sees the console - including anonymous visitors. That is fine on a local copy and dangerous on a public one. The Allowed Groups option (filter_groups) limits the console to chosen user groups.

The plugin checks it like this:

$filterGroups = (array) $this->params->get('filter_groups', []);

if (!empty($filterGroups)) {
    $userGroups = $user->groups;

    // Show debug only if the user is in one of the allowed groups
    if (!array_intersect($filterGroups, $userGroups)) {
        return false;   // not allowed - hide the console
    }
}

Set Allowed Groups to Super Users (or your developer group) so that even with debug left on by accident, normal visitors never see it.

6.2 Sensitive Values Are Redacted

The console can show request, session, and configuration data, some of which is sensitive. The plugin automatically redacts keys that look like secrets - passwords, tokens, and similar - before printing them. The match pattern covers names such as password, passwd, secret, token, and smtppass. This reduces the risk, but it is not a reason to relax: a console on a public site still leaks query structure, file paths, and version numbers that help an attacker.

Treat the Debug Console as internal information. Restrict it to a trusted group, and turn the setting off the moment you are done.

6.3 A Real Example: The 2022 Debug Disclosure

This is not a theoretical risk. I came across this myself in 2022, after one of my newly launched Joomla sites was compromised. During my investigation, I shared my findings and analysis with the Joomla Security Strike Team, who traced the issue to its root cause and implemented the fix released in Joomla 4.2.4.

Before Joomla 4.2.4, the debug output could expose sensitive request data, including a logged-in user's session and CSRF tokens, to people who were not meant to see it. An attacker who reads those tokens can hijack the session and act as that user. The Joomla project documented this as security advisory 20221001 (CVE-2022-27912), "Disclosure of critical information in Debug Mode". It affected Joomla 4.0.0 through 4.2.3 and was fixed in the Joomla 4.2.4 security release.

The fix is exactly the redaction described above: the PROTECTED_COLLECTOR_KEYS pattern was added in 4.2.4 so that password- and token-like values are masked before the console prints them. It is a sharp reminder that the safe state is not "redacted debug on a live site" but "debug off on a live site".

I wrote up how one of my own Joomla 4 sites was affected, and what I learned from it, in the Joomla Community Magazine: How my new Joomla 4 website got hacked.

8. Profiling Your Own Code

8.1 Adding Your Own Time Marks

The Profile tab is not limited to core marks. Any code can add its own using the application Profiler. Each mark records the time and memory since the request started:

use Joomla\CMS\Profiler\Profiler;

$profiler = Profiler::getInstance('Application');

$profiler->mark('myExtension: before heavy work');
$result = $this->doHeavyWork();
$profiler->mark('myExtension: after heavy work');

Both marks appear in the Profile tab, and the gap between them is exactly how long your heavy work took. This is the simplest way to measure a suspected slow method without an external profiler.

8.2 The Server-Timing Header

When profiling is on, the plugin also writes the marks into a standard Server-Timing response header. Your browser's developer tools (the Network tab) then show the same timings on the request, so you can read them without opening the console. Module render time and access-check time are summed into their own entries, which makes a slow template easy to spot.

8.3 Use the Constant to Guard Expensive Diagnostics

If your diagnostic itself is costly - dumping a large array, building a trace - wrap it in the constant so it never runs in production:

if (JDEBUG) {
    Log::add('Payload: ' . print_r($payload, true), Log::DEBUG, 'my-extension');
}

This keeps the live site fast while giving you full detail the moment you switch debug on.

8.4 When to Reach for Xdebug or a Profiler

The Debug Console is a fast first layer: it tells you where the problem is - a slow query, a heavy plugin, a slow phase of the request. To find the exact line of PHP behind that, reach for a step debugger such as Xdebug, or a code profiler such as Blackfire or Tideways. The workflow is to let Joomla's Debug point at the suspect component or query, then use the external tool to drill into the method that causes it. The two layers complement each other; neither replaces the other.

10. Language Debugging

10.1 What Debug Language Shows

Set Debug Language to Yes and Joomla marks translated text on the page so you can see the state of each string. Untranslated strings stand out, and the console gains language tabs that list:

• Language files - every .ini file Joomla loaded for this page.
• Language strings - the keys that were used.
• Language errors - keys that had no translation, or files with syntax errors.

This is the fastest way to find a missing translation: the bad key shows on the page, and the language tab tells you which file should contain it.

10.2 The Marker Characters

Translated strings are wrapped in marker characters on screen. A string with markers on both sides was translated cleanly; a string shown as its raw constant name (like COM_EXAMPLE_HELLO) has no translation at all. The Debug Language Constants option decides whether you see the constant name or its fallback value for such strings.

10.3 Stripping Long Prefixes

Joomla language keys can be long. The language fieldset of the plugin options lets you strip a common prefix or suffix from the displayed key, and the Strip First Word option removes the leading part (often the extension name). These only change how keys are shown in the console; they do not touch your translation files.

12. Web Services and the Command Line

12.1 JDEBUG Exists Everywhere

The JDEBUG constant is defined in every entry point - the site, the administrator, the API application, and the CLI. The same debug setting therefore affects them all. On the command line, Joomla's console even reports the debug state in its version line:

php cli/joomla.php --version
Joomla! 6.x.x (debug: No)

12.2 No Debug Console in JSON Responses

The Debug Console is HTML, injected before </body>. A Web Services request returns JSON, which has no body tag, so the plugin does not inject a console into API responses - it would corrupt the JSON. Instead, when data is collected for a non-HTML response, the plugin stacks it internally rather than printing it. In practice this means you debug the REST API through logs and the query monitor, not through a visible bar.

12.3 No REST Endpoint for Debug

There is no /api/index.php/v1/ route to turn debugging on or off. Debug is a configuration and diagnostic concern, not data to expose over an API. To change it from automation, edit the setting through the backend or, in a controlled deployment, the debug value in configuration.php.

12.4 No Console in Scheduled Tasks or CLI

The Debug Console only exists for an HTML page request. Joomla's Scheduled Tasks and CLI commands run with no browser response, so there is no bar to read - even with debug on. When you need to diagnose a task or a console command, fall back on the tools that do not need a page: write to the log with Log::add(), add Profiler::mark() calls to measure timing, and make sure exceptions are caught and logged. The same is true for any background work that never renders HTML.

14. Common Mistakes and Pitfalls

14.1 Debug Is On but Nothing Appears

Symptom: You set Debug System to Yes but no console shows at the bottom of the page.

Fix: Check the plugin. The System - Debug plugin must be enabled under System → Manage → Plugins. Also check Allowed Groups - if it lists a group you are not in, the console is hidden from you.

14.2 The Console Shows on the Live Site for Everyone

Symptom: Visitors report a strange dark bar with technical data at the bottom of the page.

Fix: Debug is on in production with Allowed Groups empty. Turn Debug System off in Global Configuration. As a safety net, set Allowed Groups to Super Users so this cannot happen again.

14.3 The Site Is Slow After "Fixing" Something

Symptom: The whole site feels slower than before, with no obvious cause.

Fix: Check whether debug was left on. Debug Mode disables GZIP and asset caching and records every query. Set debug back to No and the speed returns.

14.4 A White Page With No Error

Symptom: A page is blank and you cannot tell why.

Fix: Turn on Debug System and set Error Reporting to Maximum. The hidden PHP error that caused the blank page now appears, pointing at the file and line.

14.5 Passwords Visible in the Request Tab

Symptom: You worry the console is showing a login password.

Fix: The plugin redacts keys that look like secrets, but the safest answer is to never run the console where untrusted people can see it. Restrict Allowed Groups, and never enable Track Request History except for a short, supervised test.

14.6 Translations Look Fine With Debug Off but Broken With It On

Symptom: Text shows odd marker characters around it.

Fix: That is Debug Language doing its job - the markers are how it shows translation state. Turn Debug Language off and the markers disappear; they are never shown to normal visitors.

16. Quick Reference

TURN ON SYSTEM DEBUG   System -> Global Configuration -> System -> Debug Settings -> Debug System = Yes
TURN ON LANG DEBUG     same tab -> Debug Language = Yes
ERROR REPORTING        System -> Global Configuration -> Server -> Error Reporting = Maximum
THE PLUGIN             System -> Manage -> Plugins -> System - Debug
RESTRICT WHO SEES IT   System - Debug plugin -> Options -> Allowed Groups = Super Users

SETTINGS (configuration.php)
  debug             0 off / 1 on   (defines JDEBUG)
  debug_lang        0 off / 1 on
  error_reporting   default / none / simple / maximum
  log_deprecated    log deprecated API calls

CONSOLE TABS
  Info Profile Queries Memory Request Session User Log  + Language tabs

KEY PLUGIN OPTIONS
  filter_groups          who may see the console (empty = everyone)
  queries                show the Queries tab
  query_traces           add a call stack to each query (names the culprit)
  query_explains         run EXPLAIN on select queries
  refresh_assets         break asset cache each reload
  log-deprecated-core    split core vs extension deprecations
  track_request_history  save requests to disk (RISKY - off)

CODE
  Is debug on?     if (JDEBUG) { ... }
  Add a time mark  Profiler::getInstance('Application')->mark('label')
  Guarded log      if (JDEBUG) Log::add($msg, Log::DEBUG, 'my-ext')

CLI
  Show debug state php cli/joomla.php --version   ->  (debug: No)