Objective
Recover a WordPress site from a fatal PHP error by collecting the exact failure, isolating the implicated component and validating normal public access with a controlled recovery path.
- Preserve the failing component, logs and recovery point before changing it.
- Use a targeted staging test and keep public error display disabled.
- A working recovery dashboard or checksum command alone is not a completed repair.
Prerequisites
- Administrative WordPress and hosting access for the intended installation.
- A verified file/database recovery point and knowledge of recent updates.
- PHP/web-server logs and a staging copy where the failure can be reproduced.
- WP-CLI, if available, and a compatible installed fallback theme before any activation example.
Step-by-step procedure
Establish the baseline and scope
Record the failing request, time, exact PHP error and recent changes. Preserve the relevant logs and the component’s current version and state before isolating it. Reproduce on staging where possible.
- The selected devices or site, timing, previous state and expected result are recorded.
Use Recovery Mode to regain diagnostic access
If WordPress sends the administrator a Recovery Mode link, use that trusted link to inspect the failing plugin or theme. The paused component is scoped to the recovery session; access to the dashboard does not prove that normal visitors are fixed. If no email arrives, use hosting access and the relevant logs to continue diagnosis.
- The failing component is identified and normal public access is tested separately from the recovery session.
Read the PHP fatal error first
Record the failing URL or task, timestamp, error text, file and line from the hosting/PHP logs. Compare recent plugin, theme, code and PHP-runtime changes. php -v reports the command-line runtime and may differ from the web runtime. Check the hosting configuration and required extensions instead of switching PHP versions at random.
- The exact fatal error is correlated with the runtime serving the failing request.
Collect a short private debugging trace
Prefer a staging reproduction. If temporary WordPress debugging is needed, edit the existing constants before the wp-config stop-editing line, keep display disabled and use a private log path writable by the web PHP user. Do not append duplicate definitions or leave a sensitive log under a public URL. Restore the prior debugging state after collecting the relevant request.
- A short protected trace is retained, display remains disabled and the original debugging configuration is recorded for restoration.
Isolate the implicated component
Take a consistent file and database backup or verified recovery point, then change only the component indicated by evidence. Deactivate the identified plugin or test an installed compatible fallback theme on staging first. Keep its files and settings for comparison; deletion or a broad all-plugins change can obscure the cause and affect unrelated functions.
- A specific component changes the reproduced failure, with its prior activation state and version retained.
Use WP-CLI in the correct installation
Run the examples from the intended WordPress installation, or set its explicit path; multisite also needs the intended site context. The skip-plugins and skip-themes flags can bypass ordinary bootstrap failures but do not skip must-use plugins. Inspection and version checks differ from plugin deactivation or theme activation, which change the site.
- The command targets the intended installation and its result is checked in the normal web request.
Compare versions and verify core integrity
Record core, plugin, theme and web PHP versions against their compatibility requirements. Core checksum verification compares WordPress core files with the official release; use the matching version and locale when necessary. Warnings about extra root files need investigation, not automatic deletion. A clean core checksum does not verify plugins, the database or the full site’s security.
- The version mismatch or changed core files have an explanation, or that hypothesis remains unconfirmed.
Restore a coherent known-good state
If the targeted correction fails, restore the implicated code and configuration from a verified recovery point and account for any database migration made by the update. Avoid replacing newer orders or other live data with an old database as an incidental step. Retest the failing request and representative user workflows, then close temporary debugging and retain the evidence.
- Recovery restores the agreed functionality without silently discarding newer production data.
Validate the complete service
Complete the subject-specific validation below and retain the result and evidence. A command or setup phase that succeeds does not on its own establish that the whole service is ready.
- The complete intended workflow is checked using the criteria below.
Examples: observations and changes
The first block is a temporary wp-config.php example for staging, not a shell command: replace PRIVATE_WRITABLE_DIR with a private existing directory writable by web PHP, and edit existing definitions before the stop-editing line. The remaining examples run from the intended WordPress installation; replace the quoted plugin/theme slugs. Deactivation and activation change the site. The skip flags do not skip must-use plugins. No command here updates or deletes core files.
Temporary configuration on staging: replace the private writable log path and edit existing constants, with public display disabled
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', '/PRIVATE_WRITABLE_DIR/wp-debug.log' );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );Site-changing action: deactivate only the identified plugin
wp plugin deactivate 'PLUGIN_SLUG' --skip-plugins --skip-themesInspect the identified plugin state
wp plugin status 'PLUGIN_SLUG' --skip-plugins --skip-themesInspect installed themes before choosing a fallback
wp theme list --skip-plugins --skip-themesSite-changing action: activate an installed compatible fallback theme
wp theme activate 'FALLBACK_THEME_SLUG' --skip-plugins --skip-themesObserve CLI PHP only; verify the web runtime separately
php -vObserve the WordPress core version
wp core version --skip-plugins --skip-themesInspect available plugin updates; this does not install them
wp plugin list --update=available --skip-plugins --skip-themesVerify core checksums against the official release; investigate mismatches and extra-root warnings
wp core verify-checksums --include-rootValidation
The procedure is validated when:
- Normal public pages and login work outside Recovery Mode.
- The formerly failing action and representative business functions have been retested.
- The fatal error is resolved, temporary debugging is closed and the targeted change is documented.
Rollback
- Return the implicated code/configuration to a verified compatible state, considering associated database migrations.
- Protect newer live data when deciding whether a database restore is necessary.
- Restore the recorded debug settings and remove only temporary test artifacts after retaining evidence.
Troubleshooting / common errors
- No recovery email: inspect hosting logs and the administrator mail path, then use authorized hosting access.
- WP-CLI still fails with skip flags: investigate must-use plugins, wp-config and the PHP runtime.
- CLI works but web fails: compare the actual web PHP version, extensions, permissions and request context.
- Core checksum warning: match version/locale and inspect the named file; do not delete files solely because they are extra.
Official references
Keep the scope, original state, observed evidence and validated outcome with the procedure record. Consult the official documentation for the installed version.