Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
Enable MediaWiki debugging in LocalSettings.php. For a first diagnosis, turn on $wgShowExceptionDetails to expose an exception stack trace or set $wgDebugLogFile to write diagnostics to a protected server file. Add $wgDebugToolbar or $wgShowDebug only when you need their specific output, and use ?debug=true in the page URL for ResourceLoader JavaScript problems. Reproduce the fault in a private or staging wiki, then disable exposed settings and secure or remove the logs before restoring public access.
What MediaWiki debug mode changes
MediaWiki does not have one master “debug mode” switch. Its principal diagnostic settings are individual variables in LocalSettings.php, and they are false by default. Each setting exposes a different kind of evidence:
Recommended Free Tools
| Setting or method | Where output appears | What it reveals | Best use | Main risk or cost |
|---|---|---|---|---|
$wgShowExceptionDetails |
The error response in the browser | A detailed stack trace for an uncaught exception, potentially including function parameter information | One controlled reproduction of a PHP failure | It can disclose implementation details and request data to anyone who can trigger the error |
$wgDebugToolbar |
A toolbar on the page | Profiling information and collected log messages | Inspecting a request while signed in to a private development wiki | Extra page output and possible disclosure of diagnostic data |
$wgShowDebug |
Raw log messages at the bottom of the page | Immediate logger output for the current request | A quick visual check when a page-level message is sufficient | Messages are exposed in the rendered page and are not a durable log |
$wgDevelopmentWarnings |
PHP/MediaWiki warnings, depending on the request and error handling | Notices about possible errors and deprecated functions | Finding extension or code that relies on obsolete APIs | Verbose output and noise on a production site |
$wgDebugLogFile |
A server-side file | Persistent diagnostic messages from requests and components that log them | Intermittent failures, background requests, and evidence that disappears before you can read it | The file can contain sensitive data and grow until it consumes disk space |
URL parameter ?debug=true |
Browser developer tools, especially Console and Network | Unbundled or otherwise debug-oriented ResourceLoader JavaScript and its client-side errors | Separating a browser delivery or JavaScript problem from a PHP failure | It changes client-side loading only; it does not enable server-side logging |
| XDebug | An interactive debugger connected to PHP | Execution flow, variables, call stack, and breakpoints | A code path that cannot be understood from messages or traces | Requires PHP extension and environment-specific setup; overhead is unsuitable for an exposed public request |
Use the smallest setting that answers the question. Page output is fastest for a one-off test, a file is better for repeatable or asynchronous failures, and XDebug is the escalation path when you must step through execution.
Prepare a safe debugging environment
Prefer staging or a private copy
Make the change on a development, staging, or otherwise access-controlled wiki whenever possible. The official debugging guidance warns that debug output should never be enabled on a live public wiki because it can expose private information. If a production incident leaves no alternative, restrict access at the web server or network layer, enable one setting for the shortest possible reproduction, and plan the rollback before you start.
Back up and check the configuration file
- Locate the wiki’s
LocalSettings.php, normally the file that was created during MediaWiki installation. - Make a protected copy before editing it. Preserve the original file permissions and ownership.
- Open the file with a PHP-aware editor and place diagnostic assignments after the normal MediaWiki configuration is loaded. Do not put them inside a comment or a quoted string.
- Keep a record of the exact lines you add so they can be removed rather than left enabled accidentally.
A syntax error in LocalSettings.php can prevent MediaWiki from loading at all. Add one small change, save it, and request a page before adding another.
Enable the core debug switches
Start with exception details
Add this line for a controlled reproduction of an uncaught exception:
$wgShowExceptionDetails = true;When the failing request reaches an uncaught exception, MediaWiki prints a detailed stack trace instead of only a generic error. The dedicated configuration reference notes that function parameter information may also be exposed. Capture the diagnostic privately, then set the value back to false or remove the line.
Add the toolbar only when you need request profiling
$wgDebugToolbar = true;This adds a toolbar to the page with profiling information and log messages. It is useful when the problem is tied to one request and you need timing or a consolidated view of messages. Because the toolbar changes page output, test it while logged in to a restricted environment rather than exposing it to ordinary visitors.
Show raw messages at the bottom of the page
$wgShowDebug = true;$wgShowDebug appends raw log messages to the rendered page. It is a quick way to verify that a code path emitted a message, but it is not a substitute for a protected file: output can be truncated by an error, hidden by an API response, or seen by anyone who can load the page.
Surface development and deprecation warnings
$wgDevelopmentWarnings = true;This enables notices for possible errors and deprecated functions. Use it when maintaining extensions, skins, or custom code that may rely on an API scheduled for removal. Warnings can be numerous, so enable this in a development context and focus on warnings produced by the request you are investigating.
A practical starting block
If you need both a visible exception and development notices on a private wiki, the four settings can be enabled together:
$wgShowExceptionDetails = true;
$wgDebugToolbar = true;
$wgShowDebug = true;
$wgDevelopmentWarnings = true;This is intentionally broad. For a production incident, begin with only $wgShowExceptionDetails or a protected log file, then add page or toolbar output if the first evidence is insufficient.
Write diagnostics to a protected log file
Configure $wgDebugLogFile
For persistent server-side diagnostics, set an absolute path in LocalSettings.php. The documented pattern includes the database name so separate wikis do not write into one undifferentiated file:
$wgDebugLogFile = "/var/log/mediawiki/debug-{$wgDBname}.log";Choose a directory outside the public web root. The PHP or web-server account that runs MediaWiki must be able to create and write the file. If the file already exists, that account must also be able to append to it.
Verify permissions without making the log public
- Create the parent directory with ownership that permits the web-server account to write while preventing unrelated users from reading it.
- Confirm that the path is not mapped to a downloadable URL by the web server.
- Trigger one known request and verify that the file’s modification time changes and that a new message appears.
- If no file is created, check the effective PHP/web-server user, directory permissions, mandatory access controls, and the spelling of the path before enabling more page output.
Do not solve a permission error by making the whole log directory world-writable or by placing the file under the wiki’s document root.
Control growth and separate noisy components
Debug logs can become large during busy traffic or a looping error. Monitor disk usage and arrange rotation or removal after diagnosis according to your operating system’s administration practices. Keep a short retention period for temporary troubleshooting rather than allowing an unbounded file to accumulate.
When several components produce too much mixed output, MediaWiki’s grouped logging configuration, $wgDebugLogGroups, can route channels such as exceptions or ResourceLoader messages to separate destinations. The exact channel names and logger behavior depend on the MediaWiki version and any logging configuration already installed; consult the logger documentation for that version before adding groups. A group is useful when you need to follow one subsystem without drowning in unrelated requests.
Show full exception information without creating a new exposure
$wgShowExceptionDetails is a boolean whose default is false. Setting it to true prints a stack trace for an uncaught exception, but a trace can include file paths, class names, SQL or request context, and function parameters. Treat the output as confidential diagnostic material.
- Restrict the wiki or reproduce the problem on staging.
- Enable
$wgShowExceptionDetails = true;. - Repeat the exact action that failed and save the trace in a private location.
- Compare the first application frame in the trace with the extension, skin, maintenance script, or configuration change involved.
- Set the variable back to
falseor remove it, then repeat the request to confirm that detailed output is no longer exposed.
If the request does not throw an exception, this setting will not create a trace. Use a log file, toolbar, or development warnings for non-exception messages.
Debug ResourceLoader JavaScript in the browser
For a client-side failure, append ?debug=true to the page URL, for example:
https://wiki.example.test/Main_Page?debug=trueThis URL-level switch targets MediaWiki’s ResourceLoader output. Open the browser’s developer tools and inspect both the Console and Network panels:
- Console errors identify syntax errors, rejected promises, missing modules, and runtime exceptions.
- Network requests show whether a JavaScript module returned an error status, an unexpected content type, or stale content.
- With debug loading enabled, source files and module boundaries are easier to map back to an extension or skin.
The query parameter does not turn on PHP logging, exception traces, or $wgDebugLogFile. If the browser reports a server error while fetching a module, correlate the request timestamp with the server log and use server-side settings separately.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Use XDebug for step-through PHP diagnosis
When messages and stack traces show where a failure surfaced but not why the code took that path, use XDebug for interactive debugging. MediaWiki’s guide documents examples for MediaWiki-Vagrant and for command-line maintenance scripts, with environment-specific setup instructions.
- Install and enable an XDebug build compatible with the PHP version used by the process you are debugging.
- Configure the debugger and your IDE or editor to accept a connection, using the setup appropriate to the operating system, container, Vagrant environment, or remote host.
- Place a breakpoint in the extension, skin, MediaWiki service, or maintenance script that owns the suspected path.
- Start the request or command with the debugger connection enabled.
- Step through calls and inspect arguments, return values, configuration state, and caught exceptions.
- Disable the debugging trigger when finished, especially if the PHP worker is serving a public wiki.
XDebug is a diagnostic tool, not a replacement for logging. It requires a reproducible request and can add substantial execution overhead, so keep it off normal public traffic.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.A safe troubleshooting sequence
Follow this order so each step adds evidence without unnecessarily widening exposure:
- Reproduce privately. Use a staging or access-controlled wiki and record the page, action, user role, timestamp, and whether the failure is browser-only, API-only, or present in every request.
- Choose the narrowest first signal. For an obvious PHP crash, enable
$wgShowExceptionDetails. For intermittent, background, or API failures, configure$wgDebugLogFileinstead. - Confirm the destination works. Check that the log path is writable by the effective web-server user, outside the public web root, and receiving new entries.
- Add context only as needed. Turn on the toolbar for profiling or
$wgShowDebugfor immediate page output. Enable$wgDevelopmentWarningswhen deprecated or suspicious code is part of the hypothesis. - Classify browser failures. Retry with
?debug=true, then inspect Console and Network requests. A failed module request points toward delivery, permissions, caching, or PHP output; a runtime exception after successful loading points toward JavaScript code. - Step through the path. If logs cannot explain the branch or state, use XDebug with a breakpoint in a private development environment.
- Close the diagnostic window. Remove or disable temporary settings, secure or delete logs, and verify from an ordinary session that no trace, toolbar, raw message, or debug asset is exposed.
Common symptoms and corrective actions
| Symptom | Likely explanation | Action |
|---|---|---|
| The page still shows only a generic error | The request did not reach an uncaught exception, the setting was added to the wrong configuration file, or PHP is serving a cached process with an invalid reload | Verify the active wiki’s LocalSettings.php, check PHP/web-server error handling, and use $wgDebugLogFile to capture non-exception messages. |
| No debug log file appears | The parent directory is missing or not writable by the PHP/web-server account, or the path is invalid | Test directory ownership and write permission as the effective service account; use an absolute, non-public path. |
| The log exists but remains empty | The tested request emitted no message, logging is routed through another configuration, or the request reached a different wiki host | Trigger a known diagnostic request, confirm the hostname and database, and inspect grouped logger settings for the installed version. |
| The log grows rapidly | A busy wiki, repeated exception, or verbose component is writing on every request | Disable unnecessary page settings, isolate a component with $wgDebugLogGroups where supported, and rotate or remove the file after collecting evidence. |
?debug=true changes nothing |
The failure is server-side, the URL parameter was placed after a fragment, or the browser is showing cached output | Put the parameter before any #fragment, reload while watching Network, and correlate module requests with server logs. |
| Warnings overwhelm the page | $wgDevelopmentWarnings and raw output are exposing every notice on a busy request |
Move diagnostics to a protected file, disable $wgShowDebug, and enable development warnings only while investigating the relevant code. |
| Enabling debugging breaks the wiki | A PHP syntax error was introduced while editing LocalSettings.php, or a log path uses invalid quoting or an unavailable variable |
Restore the backup, validate the PHP syntax, add one assignment at a time, and check the web-server/PHP error log. |
Protect credentials and other private data
Debug output is not safe to publish. MediaWiki’s documentation warns that logs can contain login credentials, session cookies, and submitted form values; the $wgDebugLogFile reference additionally warns that private data in the file could help an attacker compromise user accounts.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minute- Keep exception pages, toolbars, raw messages, and log files behind access controls while enabled.
- Before sharing a trace or log, remove cookies, authorization headers, passwords, tokens, form fields, email addresses, IP addresses, and any other data not needed to explain the defect.
- Do not paste an unredacted log into a public issue tracker or chat room.
- Restrict file permissions and web-server exposure, and include the file in your backup and retention review because backups can preserve sensitive diagnostics.
- After the investigation, disable the settings and securely remove or rotate temporary logs according to your incident-handling policy.
Configuration examples by situation
One reproducible exception on staging
$wgShowExceptionDetails = true;Reproduce once, save the stack trace privately, then remove the line. This avoids collecting unrelated requests.
An intermittent production error with no page exposure
$wgDebugLogFile = "/var/log/mediawiki/debug-{$wgDBname}.log";Use a protected directory, verify write access, watch the file while reproducing, and rotate or delete it after diagnosis.
Extension maintenance and deprecation cleanup
$wgDevelopmentWarnings = true;
$wgDebugLogFile = "/var/log/mediawiki/development-{$wgDBname}.log";Keep the warnings in a private environment and use the log rather than rendering every notice to visitors.
Request profiling on a private development wiki
$wgDebugToolbar = true;
$wgShowDebug = true;Use the toolbar for request-level profiling and raw output only while the wiki is access-controlled. Disable both before sharing the URL.
Disable debug mode and verify the rollback
- Open
LocalSettings.phpand remove temporary assignments or set boolean switches back tofalse. - Stop or rotate the debug log and remove diagnostic files that are no longer required.
- Clear any PHP process or opcode cache only if your deployment requires it for configuration changes to take effect.
- Load the previously failing page in a private window and as an ordinary user to confirm that stack traces, toolbars, raw messages, and debug-only assets are gone.
- Check disk usage and web-server access logs for unexpected requests to the diagnostic path.
A completed investigation is not complete until the evidence is protected and the temporary visibility is gone. Leave only the narrowly scoped, documented logging that your normal operations policy explicitly permits.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
