When WordPress shows a critical error, HTTP 500, a white screen, or another technical problem, the visible error message is often not enough to identify the actual cause.
WordPress and PHP can therefore log more detailed error information. These logs show, for example, which type of error occurred, at what time the error was generated, and which PHP file was involved.
WordPress has its own debugging system for this with settings like WP_DEBUG, WP_DEBUG_LOG and WP_DEBUG_DISPLAY. Additionally, server-side PHP error logs can contain important information.
However, debugging does not mean displaying as many error messages as possible publicly on the website. On a production website, technical details should ideally be logged and subsequently analyzed in a targeted manner.
Briefly explained: Enable debugging only specifically for troubleshooting. On a production website, error messages should normally not be displayed publicly. Instead, use an error log, reproduce the error, note the timestamp, and then examine the corresponding log entries.
What does debugging mean in WordPress? #
Debugging refers to the systematic search for errors in software or a website.
With WordPress, for example, it is about figuring out why a specific request is failing, a plugin is causing an error, or PHP is aborting the processing of a page.
Instead of merely trying out different settings, debugging provides technical information about the actual execution process.
This frequently allows a suspicion to be turned into a concrete diagnosis.
When is WordPress debugging useful? #
Debugging is especially helpful when a problem occurs reproducibly, but the visible error message does not provide a sufficient explanation.
This affects, for example, critical WordPress errors, HTTP 500 errors, issues after a plugin or theme update, errors after changing the PHP version, or features that suddenly stop working correctly.
Even with unusual plugin behavior, a log can provide clues, even if the website itself remains accessible.
Debugging is not the same as repairing #
An error log does not automatically fix the problem.
Debugging helps initially to identify the cause.
If a log shows, for example, that a fatal PHP error is occurring within a specific plugin, it must then be checked why this error is occurring and what solution is suitable for it.
The strength of debugging therefore lies not in automatic repair, but in a much more precise diagnosis.
Create a backup before making changes #
Before you configuration files like wp-config.php you are editing, a current backup should be available.
A small syntax error in a PHP configuration file can cause WordPress to stop loading correctly.
For complex or mission-critical websites, a staging environment is generally preferable for extensive debugging work.
The wp-config.php file #
The main WordPress debugging settings are usually in:
wp-config.php
defined.
This file is usually located in the root directory of the WordPress installation or one level above, provided the installation has been configured accordingly.
It contains central settings of the WordPress installation and should therefore only be edited with care.
WP_DEBUG #
The central WordPress constant for debug mode is:
WP_DEBUG
In a normal productive WordPress installation, debugging is usually disabled:
define( 'WP_DEBUG', false );
It can be activated for a targeted diagnosis:
define( 'WP_DEBUG', true );
With activated WP_DEBUG increases WordPress PHP error reporting and additionally generates WordPress-specific notices, for example regarding deprecated functions.
do not put true and false in quotation marks #
Regarding the debug constants true and falsche Boolean values.
For example, correct is:
define( 'WP_DEBUG', false );
Should not be used:
define( 'WP_DEBUG', 'false' );
The second variant contains a string instead of a boolean value and can therefore lead to an unexpected result.
Important: For WordPress constants, the data type should be adopted correctly.
falscheand'false'are not the same in PHP.
WP_DEBUG_LOG #
With:
WP_DEBUG_LOG
Can WordPress write debug messages to a file?.
A typical configuration is:
define( 'WP_DEBUG_LOG', true );
If WP_DEBUG_LOG on true set and WP_DEBUG is activated, WordPress uses by default:
wp-content/debug.log
as a debug log file.
WP_DEBUG_LOG requires WP_DEBUG #
An important connection is frequently overlooked:
WP_DEBUG_LOG
works within the WordPress debug system along with:
WP_DEBUG
If WP_DEBUG is not activated, the mere setting of WP_DEBUG_LOG not the expected WordPress debug logging.
Custom path for WP_DEBUG_LOG #
WordPress can be used for WP_DEBUG_LOG also use a valid file path.
This can be useful if the error log should not be stored directly within the publicly accessible website directory.
Which paths are sensible and describable in a specific hosting environment depends on the server configuration.
WP_DEBUG_DISPLAY #
The constant:
WP_DEBUG_DISPLAY
controls whether debug messages are output within the website.
For a production website, the following combination is often more useful during diagnosis than public error output:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );This allows WordPress to log errors without intentionally displaying them to visitors on the website.
Attention: Detailed error messages can contain file paths, technical configurations, and other internal information. They should not be publicly displayed permanently on a production website.
also consider display_errors #
The actual PHP error output can also be influenced by the PHP configuration.
For a diagnostic configuration, the following can therefore be used additionally:
@ini_set( 'display_errors', 0 );
A possible combination is therefore:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );Whether PHP settings can be changed at runtime depends on the server configuration.
Where does the debug code belong in wp-config.php? #
The debug constants must be defined before WordPress is fully loaded.
In a typical wp-config.php Are they therefore in front of the well-known closing line or before wp-settings.php is integrated.
If a definition like:
define( 'WP_DEBUG', false );
exists, you should not additionally create a second contradictory definition in another place.
Find the debug.log #
In the default configuration, the WordPress debug file is located at:
wp-content/debug.log
It can be viewed, for example, via the hosting file manager or a suitable file transfer access.
The file does not necessarily have to exist already. It will be created or written to when corresponding messages can be logged.
If no debug.log is created #
If no file appears despite debugging being enabled, you should first check whether a loggable error was actually generated and whether the debug constants are set correctly.
In addition, file permissions, the configured log path, and the hosting or PHP configuration can play a role.
A missing debug.log therefore does not automatically prove that WordPress is working error-free.
Reproduce the error specifically #
One of the most effective methods in log analysis is the controlled reproduction of the problem.
For example, if clicking „Refresh“ on a specific page causes an error, first open the log or note its current state. Then, perform that exact action again.
After that, you examine the newly added entries.
This reduces the risk of confusing an old and long-irrelevant error with the current problem.
Timestamps are crucial #
On a website that has been running for a longer time, an error log can contain entries from many different situations.
A fatal error from yesterday doesn't necessarily have anything to do with the problem occurring today.
Therefore, note the exact time you reproduced the error and compare it with the timestamps in the log.
Practical Tip: Reproduce an error in a controlled manner once and note the time. This makes it much easier to distinguish relevant log entries from old protocol noise.
How do you read a PHP error? #
A PHP error often contains several useful components.
Particularly relevant are error type, error message, file path, line number, and timestamp.
A simplified example could look something like this:
PHP Fatal error: Uncaught Error ... in /wp-content/plugins/beispiel-plugin/datei.php on line 123
This means you already know that PHP has terminated execution due to a fatal error and in which code area the error became visible.
PHP Fatal error #
One
PHP Fatal error
is a fatal error that prevents PHP from continuing normal execution.
Such errors can be caused, for example, by incompatible code, missing functions or classes, memory issues, and other serious program bugs.
A fatal error is therefore particularly relevant in the case of an HTTP 500 error or a white screen.
Uncaught Error and TypeError #
Messages such as:
Uncaught Error
or:
TypeError
indicate errors during PHP execution.
A TypeError can occur, for example, when code passes a value of an inappropriate type to a function.
Such errors frequently occur with incompatibilities or faulty plugin, theme, or custom code.
Call to undefined function #
A message like:
Call to undefined function
means that PHP tried to call a function that is not available in this execution context.
Possible causes include incompatible code, a missing dependency, or an unavailable PHP extension.
The file path and the name of the function provide important clues for further diagnosis.
Class not found #
A message like:
Class ... not found
may indicate that expected program code was not loaded.
This can be caused, for example, by missing files, plugin dependencies, faulty autoloading processes, or incompatible versions.
Cannot redeclare #
At:
Cannot redeclare
for example, an attempt was made to redeclare an already existing function.
This can occur with double-loaded or overlapping code, and is therefore also of interest in the case of plugin or theme conflicts.
Allowed memory size exhausted #
The message:
Allowed memory size ... exhausted
shows that PHP has reached the allowed memory limit during execution.
This does not automatically mean that only a higher limit is needed. A plugin or process may also be consuming an unusual amount of memory.
We discuss the exact diagnosis under PHP Memory Limit in WordPress: Identify and fix errors.
Parse error and syntax error #
A syntax error occurs when PHP code is not structured correctly.
This can happen, for example, after a manual change to:
functions.php
or:
wp-config.php
happen.
Even a missing parenthesis, an incorrect character, or a faulty semicolon can cause PHP to be unable to interpret the file correctly.
A warning is not the same as a fatal error #
One
PHP Warning
is usually less severe than a fatal error.
PHP can continue execution despite a warning depending on the situation.
Warnings should still be investigated, especially if they occur frequently or are related to a specific malfunction.
However, not every warning automatically explains the error for which you opened the log.
Properly classify the notice #
Notices frequently indicate problematic or unclean code without immediately terminating execution.
When activated WP_DEBUG therefore, many error messages can become visible even though the website appears to be working at first glance.
The volume of reports must not lead to treating every entry as equally critical.
Deprecated messages #
WordPress and PHP can generate notices regarding deprecated functions or procedures.
Such reports often contain terms like:
Deprecated
A deprecation does not necessarily mean that the function no longer works. It indicates that the code in question is outdated and may become problematic in future versions.
With plugins or themes, many new deprecated messages after a version change are therefore an indication to check the extension in question for up-to-dateness and compatibility.
The highest number of reports is not automatically the biggest problem #
A plugin can generate hundreds of notices, while a single fatal error in another component actually crashes the website.
Therefore, the diagnosis should be based on relevance and not merely on which message appears most frequently in the log.
Reading file paths correctly #
A file path can provide an important clue about the component involved.
A path within:
wp-content/plugins/
leads to a plugin.
A path within:
wp-content/themes/
leads to a theme or child theme.
A path within:
wp-admin/
or:
wp-includes/
leads into the WordPress core.
A WordPress core path does not prove a core bug #
When an error message shows a file under wp-includes named, that does not automatically mean that WordPress itself is faulty.
For example, a plugin can call a WordPress core function with invalid data. The error may then become visible within the core function, even though the actual cause lies outside the WordPress core.
Therefore, the entire error context is more important than the last file path alone.
Understand Stack Trace #
In the event of severe errors, a so-called stack trace can be logged.
It shows, in simplified terms, which functions or methods were called before the error occurred.
This makes it possible to trace how PHP arrived at the point where execution was aborted.
For developers and technical support, a stack trace can therefore be much more meaningful than just the last line of the error.
Investigate plugin or theme conflicts using logs #
If a log repeatedly points to a specific plugin or theme, this component is a logical starting point for further diagnosis.
It should still be tested in a controlled manner and not simply deleted.
You can find our approach under Identifying and Resolving Plugin or Theme Conflicts in WordPress.
Error after a PHP change #
If new fatal errors, TypeErrors, or deprecated messages occur immediately after changing the PHP version, the compatibility of the involved components should be checked.
The file path in the error log can help identify an outdated plugin, theme, or custom snippet.
We explain more about this under Change PHP version for WordPress and check compatibility.
WordPress debug.log and PHP error log are not the same #
This difference is important.
The file:
wp-content/debug.log
is generated by WordPress debug logging when it has been enabled accordingly.
The hosting or PHP environment can additionally maintain its own error logs.
These server-side logs may contain errors that do not appear, or do not appear completely, in the WordPress debug log.
Which log should be checked first? #
If a PHP or server error log is available via the hosting, this is often a very good starting point for major PHP issues.
It does not require a permanent public error display and may already contain the decisive fatal error.
If sufficient information is not available there, targeted WordPress debugging can provide additional details.
Diagnose HTTP 500 with logs #
When an HTTP 500 error occurs, the browser often shows only a generic server error message.
The error log, on the other hand, may contain the underlying PHP fatal error, a memory error, or other server-side issues.
You can find the complete procedure at How to fix WordPress error 500.
Investigate critical WordPress error #
WordPress can display a critical error message for certain fatal PHP errors and, if applicable, offer a recovery mode.
Here too, logs can provide additional information about which component triggered the error.
We explain the corresponding recovery steps at WordPress shows a white screen or a critical error: What to do?.
Log AJAX errors #
An advantage of WP_DEBUG_LOG is that errors can be logged which do not appear on a normal visible page.
This is helpful, for example, with AJAX requests.
When a WordPress editor, form, or plugin uses an AJAX request and it fails on the server side, a log can provide clues to the PHP error.
WP-Cron and Background Processes #
Even errors during scheduled WordPress tasks can be difficult to spot because no visitor immediately sees a corresponding error message.
Logging is therefore also helpful with WP-Cron and other background processes.
If a planned process keeps failing, timestamps and recurring error patterns should be investigated.
REST API error #
Modern WordPress features and plugins often use the REST API.
A server-side PHP error during a REST request might not appear as a normal error message within a visible WordPress page.
Here too, logs can provide significantly more information than the user interface.
JavaScript errors are not necessarily in the PHP log #
WordPress debugging and PHP error logs focus on server-side operations.
If, for example, a menu, slider, or button in the browser does not respond, the cause may instead lie in JavaScript.
Such errors are often investigated using the browser's developer tools.
Therefore, an empty PHP error log does not prove that there are no technical errors whatsoever on a website.
CSS issues are usually not in the PHP log either #
A misrendered element can be caused by CSS, even though PHP works completely error-free.
If a website works technically, but spacings, colors, or layout are displayed incorrectly, for example, the browser developer tools are often the more suitable diagnostic tool.
Database error #
Database issues can also cause technical errors.
When WordPress debugging is enabled, additional information about database errors may be visible or logged.
However, an error in an SQL query should not be automatically „repaired“ through manual changes to the database. First, it should be determined which component generates the problematic query.
Debugging can affect the website itself #
Extensive logging generates additional file operations.
If a website produces a very large number of warnings or notices per request, enabled logging can write a massive amount of data.
Debugging should therefore be considered a diagnostic tool and not as a permanently enabled normal state of a productive website.
A debug.log can become very large #
If the same error is logged multiple times on every page view, it can:
wp-content/debug.log
to grow rapidly in a short time.
This takes up storage space and further complicates the analysis.
Therefore, after a diagnosis, you should check whether debugging has been disabled again and whether a log file that is no longer needed can be safely removed.
Logs can contain sensitive information #
Error logs can contain internal file paths, technical configurations, query information, and, depending on the faulty application, additional data.
Therefore, do not treat logs like publicly accessible text files.
When a log is passed on to support or a developer, only the snippet required for diagnosis should be transmitted, and it should be checked beforehand for any sensitive data.
Attention: Do not publish complete debug logs unexamined in public forums, tickets, or social networks. Check first what information they contain.
debug.log in publicly accessible directory #
The default path:
wp-content/debug.log
is located within the WordPress directory structure.
Depending on the web server configuration, a file stored there can potentially be accessed via HTTP. WordPress therefore points out itself that publicly accessible error logs can pose a security risk.
On production environments, logging should therefore be used in a controlled manner, and the log file should not be left around unnecessarily after diagnostics are complete.
Disable debugging again after troubleshooting #
After completing the diagnosis, a productive website should be returned to a normal configuration.
For example, a simple WordPress configuration can again:
define( 'WP_DEBUG', false );
use.
If additional debug constants were added solely for diagnostics, it should be checked whether they are still needed.
Process debug log after diagnosis #
If the log file is no longer needed, it can be removed after backing up any potentially relevant information.
If debug logging is enabled again later, WordPress or PHP can log new messages once more.
Removing an old log file does not fix the root cause, however. It merely serves to remove diagnostic information that is no longer needed.
Do not confuse old mistakes with current problems #
An existing debug.log may contain reports that are weeks or months old.
If a website shows an error today, the most obvious old fatal error should not automatically be assumed to be the cause.
The comparison with the current point in time is crucial.
Identify recurring error patterns #
If the same error keeps occurring at specific times, it may indicate a scheduled process.
For example, cron jobs, backups, imports, or security scans can regularly execute specific functions.
A temporal pattern in the log can therefore provide an important clue, even if the website functions normally between these events.
Compare logs before and after a change #
During a controlled diagnosis, you should change only one relevant variable at a time if possible.
For example, if a plugin is deactivated, reproduce the error again afterwards and compare the new log entries.
If the error disappears, that is much stronger information than a random change of five different settings at the same time.
Debugging a slow WordPress website #
An error log is not a complete performance analysis tool.
However, it can provide indications of processes that constantly generate errors or warnings and thereby cause additional load.
For a complete performance diagnosis, PHP processing, database, plugins, frontend resources, and hosting resources must also be examined.
We explain the procedure under WordPress is slow: Finding causes and improving loading time.
Query Monitor and similar diagnostic tools #
For further analyses, there are WordPress plugins that can display additional technical information.
A well-known tool is Query Monitor, for example. It allows you to examine database queries, PHP errors, hooks, HTTP API calls, and other information during a request, among other things.
Such tools are aimed primarily at developers and technically experienced users.
They should not remain permanently installed and activated simply because a website had an error at some point.
SCRIPT_DEBUG is not the same as WP_DEBUG #
WordPress also features:
SCRIPT_DEBUG
This constant is not with WP_DEBUG to equate.
It is used in particular for the development and diagnosis of WordPress core JavaScript or CSS files and is generally not required for normal PHP debugging.
Use SAVEQUERIES only selectively #
For database diagnostics, there is also:
SAVEQUERIES
This can be used to collect information on database queries.
This function creates additional memory and performance overhead and should therefore only be used specifically for diagnostic purposes.
For normal WordPress users, it is usually not the first step in standard troubleshooting.
Differentiating between debugging on staging and production #
On a development or staging environment, detailed diagnostic information can be useful because normal visitors are not affected there.
On a production website, on the other hand, greater care must be taken to ensure that technical information is not publicly exposed and that logging remains active only as long as necessary.
Therefore, the same debug configuration is not automatically suitable for every environment.
What you should better not do during debugging #
Do not simply enable the public output of all PHP errors on a production website and leave this setting permanently enabled afterwards.
Also, do not change multiple plugins, the theme, PHP, and the WordPress configuration at the same time. This makes it difficult to trace which change actually caused the error.
Do not immediately delete a component just because its file path appears in a log. First, check the context and reproduce the error in a controlled manner.
And do not send complete log files unreviewed to arbitrary third parties.
Basic rule: Reproduce the error, note the time, identify relevant log entries, and only then make a targeted change. Afterwards, test the same error again. This turns trial and error into a traceable technical diagnosis.
What information helps CURIAWEB support? #
When contacting CURIAWEB regarding a WordPress error, first describe which action triggers the error and when it last occurred.
A relevant log excerpt with a timestamp is much more helpful than a complete file with thousands of older messages.
If a fatal error occurs, the complete corresponding error message, including the file path and, if applicable, the stack trace, should be transmitted.
Also report whether WordPress, a plugin, the theme, PHP, or custom code was modified immediately before.
Remove or redact sensitive information if it is not needed for the diagnosis. You should never send passwords unprompted in an error log or support ticket.
Summary #
WordPress debugging and error logs are among the most important tools for systematic technical troubleshooting. Instead of merely guessing based on a visible error message, logs can show which error actually occurred, when it arose, and which code area was involved.
The central setting WP_DEBUG activates the WordPress debug mode. With WP_DEBUG_LOG Can messages be logged while WP_DEBUG_DISPLAY controls whether this information is displayed on the website.
On a production website, it usually makes more sense to log errors in a controlled manner rather than exposing technical details publicly. The default WordPress debug file wp-content/debug.log should also be treated as a potentially sensitive file.
During the evaluation, the error type, timestamp, file path, and, if applicable, stack trace are particularly important. A file path provides a clue, but does not always prove on its own which component is the actual cause.
After completing the diagnosis, debugging should be appropriately disabled again on a production website, and a log file that is no longer needed should be removed or handled securely.
The most important method remains simple: Reproduce the error, check the log, narrow down the cause, make a targeted change, and then test again.
