WordPress stuck in maintenance mode: fix failed updates

If your site says "Briefly unavailable for scheduled maintenance. Check back in a minute." and it has said so for longer than ten minutes, an update was interrupted and left a file called .maintenance in the WordPress root. Delete it with the file manager or SFTP and the site comes back. That fixes the symptom. The cause is usually one of four things: a PHP time limit or memory limit hit mid-update, a directory WordPress was not allowed to write to, a full disk, or a browser tab closed at the wrong moment. Until you know which, the next update will fail the same way.

This post covers the whole family: the stuck maintenance page, "Another update is currently in progress", "Could not copy file", the request for FTP credentials, a plugin update that took the site down, and how to update by hand when the dashboard is no help. Everything works with a file manager or SFTP, and each section says what to check before you change anything.

What WordPress does during an update#

An update is not one operation, and knowing the sequence tells you where each failure lands. When you update the core, a plugin or a theme from the dashboard, WordPress does roughly this:

1. Downloads a zip to a temporary location and checks it.
2. Writes a .maintenance file in the site root. From this moment visitors see the maintenance page.
3. Unpacks the zip into wp-content/upgrade/.
4. Copies the new files over the old ones, directory by directory.
5. Removes the unpacked files and the .maintenance file.
6. For a core update, runs the database upgrade the next time an admin loads the dashboard.

Steps 2 to 5 are the dangerous window, and on a healthy host it lasts a few seconds. Anything that kills PHP inside that window leaves the site in a half state: the maintenance file still there, some files new and some old, or a leftover folder in wp-content/upgrade/. WordPress is built to recover from most of this, which is why the maintenance page expires by itself, but it cannot recover from a request that never got the chance to finish.

The .maintenance file is tiny. It holds a timestamp:

<?php $upgrading = 1761000000; ?>

WordPress compares that number with the current time. If the file is less than ten minutes old, it shows the maintenance page. After ten minutes it ignores the file and serves the site as normal. So if you see the page a quarter of an hour after an update began, either the file is still being touched by a running update (rare) or the check is being served from a page cache. Both are covered below.

Fix a site stuck in maintenance mode#

The file is called .maintenance, with a leading dot, which is why people cannot find it. Files that begin with a dot are hidden in many SFTP clients and some file listings.

1. Open the file manager or an SFTP client and go to the folder that holds wp-config.php. That is the WordPress root.
2. Turn on "show hidden files". In FileZilla it is under Server, Force showing hidden files. In WinSCP it is Options, Preferences, Panels, Show hidden files.
3. Delete .maintenance.
4. Reload the site in a private window, so a cached copy of the maintenance page does not fool you.

If the site comes back, do not stop there. Open the dashboard and look at Dashboard, Updates. If WordPress offers the same update again, the previous attempt did not finish, and a half-copied core or plugin is the likely state. Go to the section on repairing a half-finished update before you run it a second time on top of the first.

If the file is gone and you still see the maintenance message, the page is coming from a cache. The usual sources are a caching plugin that stored the page while .maintenance existed, a server-side page cache, and a CDN. Clear the plugin's cache from its settings page, or if the dashboard is not reachable, delete the contents of wp-content/cache/. If you use a CDN or proxy in front of the site, purge it too - Cloudflare for websites and game servers explains which of its layers cache HTML and which do not.

A second, less common cause is a custom maintenance page. WordPress will show wp-content/maintenance.php instead of the default message if that file exists. Plugins that offer a "maintenance mode" or "coming soon" page often work by creating it. If the text on screen is not the standard sentence, look for that file, or for a maintenance plugin that is still switched on.

"Another update is currently in progress"#

The core updater takes a lock so that two browser tabs, or two admins, cannot run it at once. The lock is a row in the database, in the wp_options table, named core_updater.lock. It is released when the update finishes. If PHP dies mid-update, the row is left behind, and for the next 15 minutes WordPress refuses to start another core update with "Another update is currently in progress".

The honest fix is to wait fifteen minutes and try again. The lock has an expiry, and after it passes WordPress ignores the old row. If you cannot wait, or you want to confirm the row is the problem, delete it. On RE:NODE the panel's "Open in phpMyAdmin" button signs you in with a one-use token that expires in 60 seconds, so there is no password to type. Run this in the SQL tab, adjusting the table prefix if yours is not wp_:

SELECT option_id, option_name, option_valueFROM wp_optionsWHERE option_name = 'core_updater.lock';DELETE FROM wp_optionsWHERE option_name = 'core_updater.lock';

Check that no update is genuinely running first. Deleting the lock while an update is mid-copy invites exactly the corruption the lock exists to prevent. If the .maintenance file is present and was written within the last minute or two, something may still be working. Wait, then check again.

The same message appears for a different reason on sites with a failing scheduled task. WordPress runs background updates from its own scheduler, so a site whose cron is broken can leave the lock held by a process that never finishes. WP-Cron versus a real cron job explains how to tell, and how to make the scheduler reliable.

Why updates fail: the causes in order of likelihood#

Most failed updates come from a short list. Check them in this order, because the early ones are quick to rule out and the last ones are expensive.

Disk space. An update needs room for the zip, the unpacked copy and the new files at the same time, so a core update can briefly need three times the size of the thing it is replacing. On a small plan with a large uploads folder that is enough to fail. Look at the disk graph in the panel console, which shows disk against the limit, and clear what you do not need: old plugin zips, the contents of wp-content/upgrade/, cache folders and backup plugin archives left inside wp-content. A backup plugin that writes its archives next to the site is the most common way a small WordPress disk fills up.

Limits. A core update unpacks and copies thousands of small files, which takes a few seconds on fast storage and a good deal longer on a loaded machine. If max_execution_time is set very low, or memory_limit is small enough to be hit while unpacking, PHP stops the process mid-copy. The values to check, and how to raise them, are in PHP settings that matter for WordPress. As a rule of thumb, 256M for memory_limit and at least 60 seconds for max_execution_time is a sensible floor for updating. How much RAM does WordPress need covers the other side: a limit that PHP allows but the plan cannot supply.

Outbound connections. The server downloads the update from wordpress.org, so it needs outbound HTTPS. If DNS fails or a firewall blocks the request, you see a download error before any file is touched. That is the safest failure, because nothing changed. Try again later, and if it persists, open Tools, Site Health and read the "WordPress.org REST API" and loopback checks.

File permissions and the FTP credentials prompt#

This is the failure that confuses people the most. You click Update and WordPress shows a form asking for FTP or SFTP connection details, or fails with "Could not create directory". Neither means your password is wrong. It means WordPress tested whether it could write to its own folders and concluded that it could not.

WordPress picks a method to write files. By default it creates a small temporary file in wp-content and compares the owner of that file with the owner of the files already there. If they match, it writes directly. If they differ, it assumes PHP does not own the site and falls back to asking for FTP credentials. So the prompt is really a symptom of mixed ownership: some files were created by one user, typically whoever uploaded them over SFTP or restored an archive, and PHP runs as another.

Typical permissions, where the host lets you set them, are:

A directory needs the execute bit to be entered, which is why 644 on a folder breaks everything under it. Never use 777. It does not fix an ownership problem, it only makes every file writable by every account on the machine, and it is the first thing an attacker looks for. WordPress security hardening covers the rest of the permissions story.

Where you can run commands, the repair is two lines, run from the WordPress root:

$ find . -type d -exec chmod 755 {} +$ find . -type f -exec chmod 644 {} +

On a panel host you often cannot change ownership at all, and you rarely need to. The file manager and SFTP act on the same files that PHP serves, so files you create through them are normally writable by the site. The problem tends to appear after a restore, an archive unpacked by some other tool, or a migration that carried the old owner across. If it does, a ticket is the right route, because the fix is on the host side. SFTP: permission denied when editing files walks through how to tell a mode problem from an ownership problem.

If you know the site's files are writable and WordPress still asks, you can tell it to skip the guess by adding a line to wp-config.php, above the "That's all, stop editing" comment:

define( 'FS_METHOD', 'direct' );

This does not grant any permission. It only stops WordPress deciding for itself. If the files really are not writable, the update will now fail with a plain permission error instead of a form, which is more useful. Remove the line again once the underlying problem is fixed.

Repair a half-finished update#

When an update died partway, three kinds of leftover can remain. Deal with them in this order, and take a backup first.

1. Back up what is there. A broken site is still better than a deleted one. Take a panel backup of the server, and if you can reach the database, export it too. Testing a restore before you need it is worth reading while you are not in a hurry.

2. Clear the temporary folders. WordPress unpacks updates into wp-content/upgrade/. A healthy site has this folder empty. Anything inside is debris from a failed run, and a leftover folder is the cause of "Destination folder already exists". Delete the contents, not the folder itself. Since WordPress 6.3, plugin and theme updates also keep the old version in wp-content/upgrade-temp-backup/ so a failed update can roll back. If that folder holds a directory for the plugin you were updating and the plugin directory is broken or missing, that copy is the quickest way back to a working version: move it into wp-content/plugins/.

3. Reinstall the thing that was updating. If the interrupted update was a plugin or theme, delete its folder and upload a fresh copy, which is safe because settings live in the database, not in the plugin's files. If it was the core, do a manual core update, which is the next section. Then run the update again from Dashboard, Updates.

If the site now shows a critical error, the update finished but the new code does not work with something on your site. That is a different problem with a different log. Go to WordPress white screen and 500 errors, turn on WP_DEBUG_LOG, and read the last line of debug.log. A plugin that fails after updating can be disabled by renaming its folder under wp-content/plugins/, and the site returns at once; its settings stay in the database.

Update WordPress by hand#

Manual updates are a normal tool, not a last resort. They work when the dashboard cannot, and they are exactly as safe as the automatic route if you follow the order. This is the same method the WordPress documentation describes.

1. Take a backup of the files and the database.
2. Download the latest zip from wordpress.org and unpack it on your computer, or upload the zip and unpack it in place with the file manager, which extracts archives where they sit.
3. Deactivate nothing in advance if the dashboard is unreachable. If it is reachable, you may deactivate caching plugins first.
4. Delete the wp-admin and wp-includes folders on the server. These contain only core files; you have no content in them.
5. Upload the new wp-admin and wp-includes.
6. Upload the loose files from the root of the new package over the old ones: index.php, wp-login.php, wp-settings.php and the rest. Do not upload over wp-config.php, and do not replace wp-content.
7. Inside wp-content, you may update the default themes and the bundled plugins. Never delete your own plugins, themes or uploads folders.
8. Visit /wp-admin/upgrade.php in your browser. If the database needs updating, WordPress does it and tells you.
9. Delete .maintenance if it is still there, clear the caches, and test the front page, the login and one post.

The reason for deleting wp-admin and wp-includes rather than overwriting is that a new version removes files as well as adding them. An overwrite leaves the removed files behind, and old files can be loaded by mistake. Deleting those two folders is safe because nothing of yours is in them.

If you have a shell with WP-CLI, the same job is shorter, and it works even when the dashboard is down:

$ wp core version$ wp core download --force --skip-content$ wp core update-db$ wp core verify-checksums

--skip-content leaves wp-content alone. verify-checksums compares your core files with the official ones and lists anything modified or missing, which is a fast way to confirm that a half-finished update is now whole. It reports plugin files separately with wp plugin verify-checksums --all. WP-CLI is not part of every plan, so treat the file-manager route as the baseline, and see the final section of this post for what the RE:NODE panel gives you for it.

Plugin and theme updates that break the site#

Core updates fail less often than plugin updates, because plugin authors test against fewer setups. Three habits remove most of the pain.

Update in a copy first. A staging site is the only way to find out that an update breaks checkout before your customers do. A WordPress staging workflow shows how to build one, move changes across and avoid overwriting live orders and comments.

Update one thing at a time. Updating fifteen plugins in one click means a failure has fifteen suspects. Update, load the front page and the pages that matter, then go on. For a site that earns money, do this on a quiet hour, with a fresh backup taken just before.

Know the way out in advance. A plugin that breaks the site can be disabled by renaming its directory. To keep the site running, rename wp-content/plugins/name to name.off and reload. If you do not know which plugin it is, rename the whole plugins folder to plugins.off, which deactivates all of them at once. WordPress notices, switches them off in the database and shows the dashboard again. Rename the folder back, then reactivate one plugin at a time to find the culprit. To go back to the previous version of a plugin, download it from the plugin's page on wordpress.org, under Advanced View, Previous Versions.

Auto-updates change the stakes. WordPress applies minor core releases, which are mostly security fixes, on its own. You can control that in wp-config.php:

define( 'WP_AUTO_UPDATE_CORE', 'minor' );

The values are true (all releases), false (none) and 'minor'. Leave minor updates on. Plugin auto-updates are a per-plugin switch on the Plugins screen, and are best reserved for plugins you could lose for a day without anyone noticing. Anything that handles payments, forms or your theme's layout should be updated by a person who then looks at the site.

Prevent the next failed update#

The common thread in failed updates is that nobody had arranged for failure to be cheap. A short routine does that.

• Keep headroom. At least twice the size of the core and your largest plugin free on disk, and a memory_limit of 256M or more.
• Take a backup you have restored. Not just taken. A backup that has never been restored is a hypothesis. Backups that actually restore explains how to test one without risking the live site.
• Update when it is quiet, and watch the first few minutes. Most half-finished updates are noticed immediately by whoever started them.
• Schedule the backup before the update. A scheduled backup an hour before your usual update window means the restore point exists even if you forget. Scheduled tasks worth having shows the pattern.
• Do not close the tab. The update runs inside your request. Closing the browser while it unpacks does not always stop PHP, but it is the classic way to end up with a stuck .maintenance file.
• Keep the site's file layout clean. Backups, exports and old zips do not belong in wp-content. They fill the disk and are served to the world if the path is guessable.

What the RE:NODE panel gives you for this#

Most of what is above is host-independent, but a few pieces of the panel map directly onto the steps.

The WordPress line on RE:NODE installs WordPress on first start with wp-config.php already written for a MySQL database of its own, so the database credentials are correct from the start. The file manager has an in-browser editor, accepts drag-in and folder upload, and unpacks archives in place, which makes the manual update a matter of uploading one zip and extracting it. SFTP is on every server, with credentials per server. The console graphs show memory, CPU and disk against the plan's limits, so a disk-full update is visible before you start. The database slot opens in phpMyAdmin from the panel, which is how to remove the core_updater.lock row.

Backups are on every tier, can be taken on demand or scheduled, are stored off the machine they protect and are restored with a button, so the first step of every repair above can be one click. Schedules can run the backup before your update window. If a fix needs the host's hands - a restore from a platform copy, or file ownership you cannot change - open a ticket from the panel, which reaches all staff.

FAQ#

How long should WordPress stay in maintenance mode?

A few seconds for a plugin, up to a minute for a core update. Anything past ten minutes means the update stopped. WordPress itself ignores a .maintenance file older than ten minutes, so a page still showing after that is usually cached or comes from a maintenance plugin.

Is it safe to delete the .maintenance file?

Yes. It contains only a timestamp, and WordPress recreates it for each update. The risk is not in deleting it but in assuming the update finished. After deleting it, check Dashboard, Updates, and if the same update is offered again, repair it before retrying.

Will I lose content if an update fails?

Posts, pages, comments and settings live in the database, which an interrupted file copy does not touch. Plugin and theme files and the core can be left half-written. Uploads are not changed by updates. You should still take a backup before any repair.

Why does WordPress ask for FTP details when I click update?

Because it found that the owner of the files it would write is not the user PHP runs as, so it assumes it needs outside credentials. The cause is ownership or mode, not a password. Fix the permissions, or ask the host to, rather than typing credentials in.

Can I update plugins from the dashboard on a staging copy and then copy the result?

Yes, and it is the safest way. Update on staging, test, then repeat the same updates on the live site, or move the changed files across. Do not copy the database from staging over a live shop, because you would lose the orders placed since you cloned it.

My update succeeded but the site shows a critical error. What now?

The new code conflicts with your theme, another plugin or your PHP version. Rename the plugin folder to switch it off, restore the site, and read wp-content/debug.log to see which file failed and why. Then check the plugin's changelog for a new PHP requirement.