Repair a broken WordPress site

The Site health row on a hosting’s WordPress tab asks the site’s own front page how it is doing and, when it answers with a server error, names the plugin or theme that caused it. It also gives you fixes that work while WordPress cannot start, which wp-cli based fixes cannot.

Before you start

• You hold the Manage WordPress (plugins, staging, …) permission for the hosting.
• The hosting is on a node that is online. The check runs on the node that owns the hosting.
• A recent backup exists. Open the hosting’s Backups tab and check that the newest entry shows the state ok. The steps below do not delete anything, but a backup is the way back if a site is damaged in another way.

Steps

Read the Site health row

1. Open Hostings in the sidebar, click the hosting, and open the WordPress tab.
2. Find Site health in the Health & checks group. It loads on its own and shows one of these summaries:
   • Front page answers HTTP <code>, no fatal error: the page answered with a status below 400.
   • HTTP <code> — visitors see WordPress's "critical error" page: the page answered 500 or higher.
   • Front page answers HTTP <code>: a status of 400 or higher, but not a server error. The row adds a hint for 404 (the document root is missing or empty) and for 401 and 403 (an access rule or a document root nginx cannot read).
   • No answer from the front page: nginx is not serving the domain on port 443, or the page took longer than 15 seconds.
3. Click Check again after any change to run the probe again.

The probe asks nginx on the same server directly over loopback with the site’s host name, so DNS plays no part and a TLS certificate problem does not hide the answer.

Switch off the plugin that crashes the site

When the status is 500 or higher, Hyperion also runs wp-cli against the site. If the error names a file under wp-content/plugins/ or wp-content/themes/, the row says The crash comes from the plugin <slug> (or theme) and shows the error line.

1. For a plugin, click Disable <slug> (rename folder) and confirm with Rename & disable.
2. Hyperion renames wp-content/plugins/<slug> to wp-content/plugins/<slug>-old. WordPress then starts without it. This needs nothing from PHP, so it works while the site is down. Nothing is deleted.
3. Click Check again. The row shows the new status.

The same action is available from a shell:

hctl wp fatal-check example.com
hctl wp disable-plugin example.com broken-plugin

If the crash comes from a theme, or no single plugin can be blamed, the row says so and points at debug mode. Click Enable debug mode… and confirm. That writes WP_DEBUG and WP_DEBUG_LOG to wp-config.php, so the real error lands in wp-content/debug.log without being shown to visitors. Switch it off again when you have the cause; see Use the WordPress tools.

Restore a plugin you parked

After the site answers again, the row shows Disabled by emergency rename with one Restore <slug> button for each parked folder.

1. Update or replace the plugin first, so it no longer crashes.
2. Click Restore <slug> and confirm with Restore folder.
3. The folder is renamed back and the plugin is deactivated. It comes back switched off on purpose. Activate it under Plugins once you are ready.

Restore refuses to run when a folder with the original name exists again, for example because the plugin was reinstalled in the meantime.

Park the Redis drop-in

WordPress loads wp-content/object-cache.php before any plugin, whether or not the plugin that created it is installed. When Redis stops answering, that file stops the whole site, and wp-cli too, so deactivating or deleting the Redis plugin fails.

1. In Site health, when wp-content/object-cache.php exists, the row shows Redis object-cache drop-in is active. Click Park object-cache.php and confirm with Park it.
2. Hyperion renames the file to object-cache.php.hyperion-disabled. WordPress falls back to its database cache. Nothing is deleted.
3. When Redis answers again, the row shows Redis drop-in is parked. Click Restore object-cache.php and confirm with Restore. If Redis is still unreachable, the site stops again on the next request.

Check that it worked

The Site health row reads Front page answers HTTP 200, no fatal error (or another status below 400) and shows no red callout. Visit the site in a browser to confirm the page loads.

If it fails

• “hosting root … is unreadable” or “… is a symlink — refusing to operate through it”: the plugins folder cannot be used safely. Open the Files page of the hosting and check that wp-content/plugins is a normal directory.
• “disable: … is not a directory — nothing to disable”: the plugin folder is already gone or has a different name.
• “restore: … already exists — refusing to overwrite it”: a folder with the original name exists again. Delete or move the new copy yourself if you want the old one back.
• “Nothing to move — there is no object-cache drop-in here.”: the drop-in is not present. The site’s problem is elsewhere.
• The row says Could not check: the owning node did not answer. Check the node on the Nodes page.
• No culprit is named: the error may be in the theme, wp-config.php or PHP itself. Enable debug mode and read wp-content/debug.log, or run Repair or reinstall WordPress to replace core files.