Troubleshooting · Guide
How to Troubleshoot WordPress Without wp-admin Access
Short answer
Check the admin email for the Recovery Mode link first, since it logs you in with the broken plugin paused. If no email arrived, rename the faulty plugin folder over FTP, or rename the whole plugins folder to turn every plugin off at once. Turn on WP_DEBUG_LOG in wp-config.php and read wp-content/debug.log to find the file behind the error.
Key takeaways
- Recovery Mode, built into WordPress since version 5.2, pauses the faulty plugin only for your login session.
- Renaming a plugin folder over FTP deactivates that plugin at once, and renaming the whole plugins folder turns them all off.
- WP_DEBUG_LOG writes errors to wp-content/debug.log, where the file path names the plugin or theme behind the error.
- WordPress ignores the .maintenance file 10 minutes after the time recorded inside it.
- WP-CLI can list, deactivate, and reactivate plugins from the server shell when the dashboard will not load.
What usually locks you out of wp-admin?
A broken plugin or theme is the most common cause, since WordPress loads plugin code before it loads the admin screen.
One bad plugin file can kill the whole dashboard before you ever reach the Deactivate button. A failed update, a stuck maintenance file, a wrong setting in wp-config.php, or a full disk can do the same thing.
The symptom tells you where to start. A “critical error” message points at a fatal PHP error, a white screen points at a PHP error with no message shown, and a “briefly unavailable” message points at a stuck update.
Do not panic and do not start deleting things. Work through the steps below in order, from the least risky to the most direct.
What is the first thing to try?
Check the admin email inbox for the Recovery Mode message before you touch any files.
Since WordPress 5.2, a fatal PHP error triggers an email to the site administrator with a recovery link. The WordPress.org Recovery Mode documentation says the feature can help you regain access when a fatal error occurs, without FTP or editing code.
The email subject looks like “Your Site is Experiencing a Technical Issue.” It names the error and the file where it happened, and it holds a special link that logs you in with the broken plugin paused.
If the email is not in the inbox, check spam and junk folders. If your server email is unreliable, the message may never arrive, and you should move on to the FTP steps below.
How does WordPress Recovery Mode work?
Recovery Mode is a safe session that pauses the faulty plugin or theme only for you, so you can log in and fix it.
WordPress enters Recovery Mode by itself when it detects a fatal PHP error during a regular page load. The WordPress.org Recovery Mode documentation explains that visitors still see the error, but you can log in through the recovery link and work safely.
- Open the recovery link from the admin email and log in.
- Look for the notice that names the plugin or theme that failed.
- Go to Plugins or Appearance > Themes and deactivate the faulty item.
- Fix the underlying problem, such as a bad edit to functions.php.
- Click Exit Recovery Mode and check the site loads normally.
The recovery link is typically valid for one day, according to Denva Studio's recovery guide. If the link has expired, trigger a fresh error by loading the site once, and WordPress sends a new email.
Recovery Mode is the safest first step because it uses WordPress's own deactivation process. Renaming a folder over FTP only stops the code from loading, while a normal deactivation also runs the plugin's cleanup steps.
How do you deactivate plugins over FTP?
Rename the plugin folder over FTP or in your host file manager, and WordPress stops loading that plugin at once.
- Connect with FTP or open your host file manager.
- Open the
wp-content/pluginsfolder. - Find the folder of the plugin you suspect, such as
contact-form-7. - Rename it, for example to
contact-form-7-off. - Reload the site and try wp-admin again.
The WordPress.org Recovery Mode documentation gives the same method: rename /wp-content/plugins/hello-dolly to wp-content/plugins/hello-dolly-1/ to deactivate the Hello Dolly plugin.
If you do not know which plugin broke, rename the whole plugins folder to plugins-off. That turns off every plugin at once, and the dashboard should load. Rename it back to plugins afterwards, then reactivate plugins one by one until the site breaks again.
The debug log tells you which plugin to rename first. Read the newest fatal error at the end of wp-content/debug.log, since the file path in the entry names the plugin folder.
How do you switch themes without the dashboard?
Rename the active theme folder over FTP, and WordPress falls back to a default theme.
- Connect with FTP or open your host file manager.
- Open the
wp-content/themesfolder. - Rename the active theme folder, for example
my-themetomy-theme-off. - Reload the site. WordPress switches to a default theme such as Twenty Twenty-Five if one is installed.
If no default theme is installed, the site shows an error saying the theme is missing. Upload a default theme folder, such as Twenty Twenty-Five, into wp-content/themes first, then rename the broken theme.
A theme is the likely cause when wp-admin works but the front page does not, or when the break followed a theme update. A plugin is the likely cause when nothing loads at all.
Rename the theme folder back once you know the theme was not the cause. Renaming only stops the theme from loading; it does not delete any of its files or settings.
How do you read the error without wp-admin?
Turn on WP_DEBUG and WP_DEBUG_LOG in wp-config.php, load the broken page once, then read wp-content/debug.log over FTP.
Add these three lines above the “stop editing” line in wp-config.php:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
The WordPress debugging handbook states that WP_DEBUG is false by default and that WP_DEBUG_LOG writes errors to a debug.log file in the wp-content directory.
Load the broken page once, then download wp-content/debug.log and read the newest fatal error at the end of the file. The entry names the file and line number, and the folder in the path names the plugin or theme.
Log times are in UTC, not local time, according to the WordPress debugging handbook. Match the entry time to the UTC time of the failure.
Turn logging off when you finish. If the error leaves you with a blank page, our white screen fix guide walks through the same recovery steps.
How do you fix a stuck update without wp-admin?
Delete the .maintenance file from the site root over FTP, then run the interrupted update again or roll back the item that broke.
WordPress creates a .maintenance file during every update and shows “Briefly unavailable for scheduled maintenance” while it exists. If the update is interrupted, the file stays behind and the message never clears.
WordPress ignores the .maintenance file 10 minutes after the time recorded inside it, so a stuck message sometimes clears on its own. That detail comes from Simafri's WordPress rollback guide.
If the message stays, delete the file over FTP or in your host file manager. Then open Dashboard > Updates and run the interrupted update again, or reinstall the item at its previous version.
Our stuck maintenance mode fix guide covers the same steps, including what to do when the update keeps failing after the file is gone.
How do you use WP-CLI to troubleshoot?
WP-CLI runs WordPress commands from the server shell, so it works even when the dashboard will not load.
| Command | What it does |
|---|---|
wp plugin list | Lists every plugin with its status and version |
wp plugin deactivate --all | Turns off every plugin at once |
wp plugin deactivate hello | Turns off one plugin by its folder name |
wp plugin activate hello | Turns one plugin back on |
wp core version | Prints the WordPress version the site runs |
The Make WordPress Hosting WP-CLI handbook page recommends this exact sequence when a plugin breaks a site and the dashboard is not reachable: run wp plugin deactivate --all, then wp plugin activate your-plugin-slug one plugin at a time.
The WP-CLI plugin deactivate documentation confirms that wp plugin deactivate --all deactivates all plugins, and that --exclude keeps named plugins active, for example wp plugin deactivate --all --exclude=hello,wordpress-seo.
Use WP-CLI only if your host gives you SSH access. Many shared hosts do not, and the FTP steps above are the fallback in that case.
When should you call your host?
Call your host when the problem sits outside WordPress, such as a server error, a full disk, or a database that will not connect.
Signs that point at the host are a 500 or 503 error on every page including a plain HTML file, a database connection error with no recent change to wp-config.php, or a disk quota warning in your control panel. Your host can also restore a server backup when no WordPress backup exists.
Before you call, note the exact error message, the time it started in UTC, and what changed just before it. That list saves a long back-and-forth and gets you to the right fix faster.
If your host offers a one-click restore, ask how far back its backups go and whether the restore covers the database as well as the files. Our guide to host backups explains what host backups cover and where they fall short.
What mistakes should you avoid?
Never delete files to fix a lockout, since deactivation is enough and deletion loses settings and data.
- Do not rename the whole wp-content folder, since that breaks every plugin and theme at once.
- Do not edit the database by hand unless every other route has failed, since one wrong value can break logins.
- Do not leave WP_DEBUG on after the fix, since the log keeps growing and may expose file paths.
- Do not skip the backup before you start renaming things, since a wrong rename is easy to undo only if you know the old name.
If you are locked out and nothing here works, restore a backup from before the problem. Our UpdraftPlus restore guide covers the restore steps.
WordPress 5.2 added a fatal error handler so users are not locked out when a theme or plugin causes a fatal error. That detail comes from the WordPress.org theme handbook debugging page, and Recovery Mode is the feature that puts it to work.
Frequently asked questions
I never got the Recovery Mode email. What now?
Check the admin email inbox and the spam folder for a message with the subject Your Site is Experiencing a Technical Issue. It holds a recovery link that is typically valid for one day. If no email exists, rename the faulty plugin folder over FTP or in your host file manager.
Can I turn off all plugins at once without the dashboard?
Yes. Rename the whole wp-content/plugins folder to plugins-off over FTP, which turns off every plugin at once. The dashboard should load again. Rename the folder back to plugins, then reactivate plugins one by one until the site breaks, which names the culprit.
What happens if I rename the active theme folder?
WordPress switches to a default theme such as Twenty Twenty-Five if one is installed. If no default theme is installed, the site shows an error saying the theme is missing, so upload a default theme folder into wp-content/themes first.
How do I read the error when I cannot open the dashboard?
Add WP_DEBUG, WP_DEBUG_LOG, and WP_DEBUG_DISPLAY set to false in wp-config.php, above the “stop editing” line. Load the broken page once, then download wp-content/debug.log over FTP and read the newest fatal error at the end of the file.
My site says briefly unavailable for scheduled maintenance. How do I clear it?
Delete the .maintenance file from the site root over FTP or in your host file manager. WordPress creates it during every update and ignores it 10 minutes after the time recorded inside it, so a stuck message sometimes clears on its own. Then run the interrupted update again.
When should I call my host instead of fixing it myself?
Call your host when the fault sits outside WordPress, such as a 500 error on every page, a database that will not connect, or a full disk. Your host can also restore a server backup when no WordPress backup exists. Note the exact error and the time it started before you call.
Sources
- Recovery Mode WordPress.org
- Debugging in WordPress WordPress Developer Resources
- wp plugin deactivate WordPress Developer Resources
- WP-CLI Make WordPress Hosting
- How to Find and Access WordPress Error Logs WPBeginner
- WordPress Site Down After Update: Step-by-Step Recovery Guide Denva Studio
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
