FIELD GUIDE · TROUBLESHOOTING

How to troubleshoot WordPress without making a bad day worse

A practical, evidence-first process for diagnosing errors, isolating conflicts and bringing a site back safely.

When a WordPress site breaks, the urge to change everything at once is understandable. Resist it. A blank screen, a 500 response or a failed login can have several causes, and a rushed fix can make it harder to tell what actually happened. The goal is not simply to make an error disappear; it is to identify a likely cause, restore a working experience, and leave enough evidence to prevent a repeat.

This guide is for site owners who can access their WordPress dashboard or hosting account. Instructions vary by host and setup. Use a staging copy when possible, and ask your hosting provider or a qualified developer for help before changing files or database settings you do not understand. If a store, booking system or membership site is involved, consider the effect on customers and transactions before taking anything offline.

1. Protect the site before you investigate

Start with a fresh, restorable backup of both the database and site files. The database contains content and settings; uploads, themes, plugins and other files live separately. A database export alone is not a complete site backup. Confirm where the backup is stored and how to restore it. If the site is already failing, a backup still preserves the current state, but it does not replace a known-good earlier copy.

Check whether your host offers a staging environment or an isolated clone. Test disruptive changes there first. For a busy site, coordinate a maintenance window and let the people responsible for orders or publishing know what is happening. Do not restore an old database casually: it may discard orders, submissions or edits created after the backup was taken.

Write down what is broken, when it started and who is affected. Capture the exact error message, the URL, browser and device, and the time and time zone. Note any recent plugin, theme, core, PHP, DNS or hosting changes. A screenshot and a short list of changes are often more valuable than a collection of speculative fixes.

2. Decide whether the problem is local or site-wide

Open the affected page in a private browser window, then try a different browser or device. Ask another person on a different network to check it. If only one person is affected, clear their browser cache and examine extensions before changing the website. If the page works for administrators but not visitors, compare logged-in and logged-out views; caching or access rules may be involved.

Check several URLs: the home page, a normal page, the login screen and an asset such as an image. A single broken page suggests a different investigation from a site-wide outage. If the server returns an error before WordPress loads, hosting or infrastructure may be involved. If the site is unreachable everywhere, ask the host whether there is a known outage, a resource limit or a server-level error.

Make one change at a time and record the result. A useful note includes the original state, the precise action, the time and whether the same test now passes. If a change does not help, reverse it before trying another. This keeps the investigation understandable and makes escalation much easier.

3. Use Site Health and logs as clues

If you can sign in, open Tools → Site Health. Review critical issues and recommendations, but treat them as starting points rather than a diagnosis. A warning is not necessarily the cause of the current incident. The information tab can help you describe the environment to support without guessing versions or server details.

Ask your host where to find PHP and web-server error logs. Look for entries at the time of the failure and note the named file, plugin or theme. A stack trace is evidence, not a guarantee that the final item listed is the underlying cause. Logs can contain private paths, email addresses and request data, so share them only with trusted people and remove secrets where appropriate.

WordPress also has debugging constants for development and staging. WP_DEBUG_LOG requires WP_DEBUG; WP_DEBUG_DISPLAY can keep messages out of the rendered page. WordPress recommends debugging tools for local or staging environments rather than normal live operation. Do not leave public debug logs accessible, and disable temporary debugging after investigation. Follow the official documentation or ask your host to help configure logging safely.

4. Isolate plugin and theme conflicts

A recent update or newly enabled extension is a useful lead, but do not assume it is guilty without testing. On staging, disable plugins and repeat the exact failing action. If the issue disappears, reactivate plugins one at a time, repeating the test after each activation. If the error returns, note the plugin and its version. A conflict can involve two extensions rather than one defective plugin, so test combinations carefully.

Disabling an extension can temporarily remove forms, security features, payments or other important functionality. That is why staging and a coordinated maintenance window matter. Do not delete a plugin simply to test it; deleting is a separate action and some plugins can remove data during uninstall. Confirm the effect of disabling each essential plugin before proceeding on a live site.

If you cannot access the dashboard, your host can help temporarily rename the plugins directory using a file manager or secure file transfer. WordPress documents this recovery method. Rename it back before reactivating plugins individually. Be aware that this can disable every plugin and does not necessarily affect must-use plugins. Avoid editing the database directly unless you understand the consequences and have a backup.

On staging, switch temporarily to a standard WordPress theme to see whether the active theme is involved. A theme change can alter menus, widgets, templates and appearance, so document the original configuration and do not casually switch the production site. If the default theme resolves the symptom, share the findings and reproduction steps with the theme developer.

5. Work through common symptoms

A blank page or critical error

Check the administrator email for a WordPress recovery message and review the relevant logs. A fatal PHP error, plugin conflict or incompatible code can prevent a page from rendering. Record the named file and version before changing anything. If recovery mode is available, use its instructions to regain access and isolate the extension. When in doubt, ask the host to help interpret the log instead of editing core files.

“Error establishing a database connection”

This message means WordPress cannot establish its database connection. It does not by itself prove that data has been lost. Confirm with the host that the database service is running and that the database has not reached a limit. If credentials or the database host recently changed, compare the configuration with the host’s current details. Never post database passwords in support forums or screenshots.

500 errors and timeouts

A 500 response is a broad server error, not a specific diagnosis. Check the server log around the request time, available resources and recent changes. On Apache, rewrite rules or a damaged .htaccess file can be one possible cause, but server configurations differ. Do not overwrite configuration files without a backup and a clear rollback plan. A timeout may involve slow code, resource limits or an external service; your host can help locate the bottleneck.

404 pages or changes that do not appear

First verify the requested URL and whether the page is published. If many pretty URLs fail after a migration, review Settings → Permalinks and your host’s rewrite configuration; saving settings may refresh rewrite rules, but it cannot fix every server setup. For stale content, check browser, page, server and CDN caches in order. Clear only the relevant cache where possible and retest in a private window.

Stuck in maintenance mode

Updates may create a temporary .maintenance file in the WordPress root. If an update is genuinely no longer running and the message persists, consult your host before removing that file. Then check whether the update completed correctly. Do not interrupt a running update or assume that clearing the message has repaired an incomplete update.

6. Recover access without exposing secrets

Check the login URL, keyboard layout and password manager before attempting recovery. Use the normal password reset flow and inspect the spam folder. If the reset email does not arrive, the site’s mail configuration may be the issue; your host can help. Do not send passwords, authentication codes, private keys or a full configuration file by email or through an ordinary contact form.

If you suspect a compromised account, treat the situation as a security incident rather than a routine login problem. Preserve logs, involve your host and follow a documented recovery process. Reset credentials through trusted channels, inspect administrator accounts and plugins, and review access after the site is clean. A successful login alone does not establish that the underlying compromise is resolved.

7. Restore carefully and verify the result

A known-good backup can shorten an outage, but a restore is not always the first or safest action. Identify exactly what will be replaced, when the backup was taken, and which new records might be lost. For sites with ongoing transactions, coordinate with the host or developer on how to preserve recent data. Restore to staging first whenever possible and compare the restored version with the live site.

After a fix, test the original failing action and a small set of critical journeys: open pages, sign in, submit a form, complete a safe test transaction if applicable, and check on mobile. Confirm the expected status in monitoring and inspect logs for new errors. Clear only necessary caches. Ask a second person to repeat the test when the issue depends on location, permissions or device.

Close the incident with a short record: symptom, confirmed or suspected cause, changes, backup or rollback point, verification and any follow-up. If the exact cause remains uncertain, say so. Schedule a follow-up for updates or improvements and review whether the backup and monitoring process gave you enough time to respond.

When to ask for help

Escalate promptly when database errors persist, the server is unavailable, security is in doubt, customer data could be lost, or the fix requires unfamiliar file or database changes. Send a concise timeline, the affected URL, sanitized error text, versions and steps already tried. Never include credentials. The WordPress support forums, your hosting provider and the relevant plugin or theme developer are useful routes depending on the evidence.

Further reading: WordPress common errors · Troubleshooting FAQ · Debugging in WordPress · WordPress backups.