WP-CLI troubleshooting tutorial (2026): Fix broken WordPress updates, stuck plugins, and permissions on a VPS

A WordPress site rarely “breaks” because core is flimsy. It usually fails because an update stops mid-write, a plugin throws a fatal on PHP 8.x, or ownership and permissions drift after a migration. When that happens, SSH is often the fastest way back.

This WP-CLI troubleshooting tutorial focuses on repeatable command-line fixes for VPS and dedicated servers.

You’ll use WP-CLI to disable misbehaving plugins without wp-admin, clear update locks, repair file ownership, and restore a clean, updateable state.

Examples assume Ubuntu 24.04/26.04-class servers with Nginx or Apache and PHP-FPM. The same workflow applies to Debian 12/13, AlmaLinux, Rocky, and most control-panel VPS setups.

Before you touch anything: confirm you’re in the right WordPress and take a quick snapshot

During an outage, it’s easy to run commands in the wrong docroot. It’s also easy to run them as the wrong user. Spend two minutes confirming paths and giving yourself a rollback point.

1) Find the WordPress document root

Nginx: check /etc/nginx/sites-enabled/ and look for root.
Apache: check /etc/apache2/sites-enabled/ (Debian/Ubuntu) or /etc/httpd/conf.d/ (RHEL-like) and look for DocumentRoot.

From the docroot, confirm you’re in a WordPress install:

cd /var/www/example.com/public
ls -la | head
test -f wp-config.php && echo "wp-config.php found"

2) Take a fast rollback point (recommended)

If your VPS uses LVM or Btrfs, take a snapshot before you change files. If you prefer offsite backups, use your existing tooling.

Make sure restores are tested, not just “configured.”

Snapshot approach: see Snapshot Backup Tutorial (2026).
Offsite 3-2-1 approach: see VPS Backup Strategy Tutorial (2026).

If you’re hosting revenue sites and want fewer late-night recoveries, a managed VPS hosting plan from HostMyCode can cover backup verification, patching cadence, and incident help. You get that support without staffing an ops team.

Install WP-CLI safely (or verify it) on a VPS

Many servers already have WP-CLI installed. Don’t guess. Check the binary and version first.

wp --info

If that fails on Ubuntu/Debian, install a pinned, system-wide binary:

sudo -i
curl -L https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar -o /usr/local/bin/wp
chmod +x /usr/local/bin/wp
wp --info

Rule: run WP-CLI as the site owner user whenever possible. Running as root often leaves root-owned files behind. Those files later block web-based updates.

If you must run as root, use --allow-root. Then correct ownership afterward.

WP-CLI troubleshooting tutorial: establish a “known-good” baseline

Before you change anything, grab a quick baseline. You want to know what WordPress thinks is installed, what’s active, and whether the config/DB connection looks sane.

cd /var/www/example.com/public
sudo -u www-data wp core version
sudo -u www-data wp plugin list --status=active
sudo -u www-data wp theme list
sudo -u www-data wp config get DB_NAME

If your web server user isn’t www-data (common on cPanel/DirectAdmin), swap in the correct account. On many stacks, it’s the site user, not the daemon user.

Fast check: can WP-CLI load WordPress?

sudo -u www-data wp option get siteurl

If you hit a PHP fatal here, WordPress is crashing during bootstrap. The usual cause is a plugin or theme. Next you’ll bypass that without relying on wp-admin.

Recover from a white screen or 500 error by disabling the offender (without wp-admin)

A common incident pattern looks like this: you update a plugin, and the site immediately returns 500. The dashboard is usually down too.

WP-CLI lets you deactivate plugins and switch themes from SSH.

1) Identify the fatal quickly

Start with the error log. These commands usually reveal the failing file and line number:

# Nginx + PHP-FPM (common)
sudo tail -n 80 /var/log/nginx/error.log

# Apache (common)
sudo tail -n 80 /var/log/apache2/error.log

If you want a more methodical workflow (timestamp, URI, and traffic spikes included), use this VPS log analysis tutorial. Keep it in your runbook.

2) Disable all plugins (fastest path to restore wp-admin)

cd /var/www/example.com/public
sudo -u www-data wp plugin deactivate --all

If WP-CLI can’t bootstrap because the fatal triggers too early, remove WordPress from the plugin-loading path. The quickest method is renaming the directory:

cd /var/www/example.com/public/wp-content
mv plugins plugins.disabled.$(date +%F-%H%M)

Once the site is back, restore the folder name. Then re-enable plugins one by one until the failure returns:

cd /var/www/example.com/public/wp-content
mv plugins.disabled.2026-09-18-1200 plugins

cd /var/www/example.com/public
sudo -u www-data wp plugin activate akismet
sudo -u www-data wp plugin activate wordfence
# Continue until the failure returns; last one enabled is your suspect

3) If the theme is the problem, switch to a default theme

cd /var/www/example.com/public
sudo -u www-data wp theme list
sudo -u www-data wp theme activate twentytwentyfour

If no default theme is installed, install one:

sudo -u www-data wp theme install twentytwentyfour --activate

Fix “Briefly unavailable for scheduled maintenance” and failed updates (.maintenance + update locks)

This isn’t about staging or change management. It’s cleanup after an update dies mid-flight and leaves WordPress stuck.

1) Remove the .maintenance file

cd /var/www/example.com/public
ls -la .maintenance
rm -f .maintenance

2) Clear stuck update locks

WordPress sets a transient lock during updates. If it never clears, future updates won’t start.

sudo -u www-data wp transient delete core_updater.lock 2>/dev/null || true
sudo -u www-data wp option delete core_updater.lock 2>/dev/null || true

3) Re-run the update cleanly

sudo -u www-data wp core update
sudo -u www-data wp plugin update --all
sudo -u www-data wp theme update --all

If this keeps happening during plugin updates, keep this maintenance mode troubleshooting tutorial handy. It covers prevention as well as recovery.

Repair file ownership and permissions so updates work again (without making the server insecure)

After a migration, restore, or a quick “just run it as root” fix, WordPress files often end up owned by root. The symptoms are consistent: updates fail, uploads error out, and cache plugins can’t write.

1) Determine the correct owner user/group

Common setups look like this:

Nginx/Apache runs as www-data (Ubuntu/Debian default).
Files are owned by a dedicated user (example), and PHP-FPM pools run as that user (common on VPS hosting setups and control panels).

Check what you have right now:

cd /var/www/example.com/public
stat -c "%U:%G %n" wp-config.php
stat -c "%U:%G %n" wp-content

2) Set sane permissions

A safe baseline for many VPS setups:

Directories: 755
Files: 644
wp-config.php: 640 (or 600 if the web user isn’t the file owner)

Example (replace siteuser and www-data):

cd /var/www/example.com/public
sudo chown -R siteuser:www-data .
sudo find . -type d -exec chmod 755 {} \;
sudo find . -type f -exec chmod 644 {} \;
sudo chmod 640 wp-config.php

Pitfall: don’t “solve” write issues with chmod -R 777. It hides the problem by letting anything write anywhere, including compromised processes. On multi-tenant systems, it can also become a cross-account incident.

3) Confirm WP can write where it needs to

sudo -u www-data wp eval 'var_dump( wp_is_writable( WP_CONTENT_DIR ) );'

Force a clean core re-download without touching wp-content

If core files are corrupted (common after a disk-full event or an interrupted update), reinstall core. This keeps plugins, themes, and uploads intact.

cd /var/www/example.com/public
sudo -u www-data wp core verify-checksums
sudo -u www-data wp core download --force

If your site uses a non-standard locale, include it:

sudo -u www-data wp core download --force --locale=en_US

Fix database connection errors by validating wp-config and checking service health

“Error establishing a database connection” usually comes from config drift after a move. The other common cause is a DB service that stopped.

WP-CLI helps because it shows what WordPress is actually trying to use.

1) Validate DB settings in wp-config.php

cd /var/www/example.com/public
sudo -u www-data wp config get DB_HOST
sudo -u www-data wp config get DB_NAME
sudo -u www-data wp config get DB_USER

2) Confirm the DB service is up

# MySQL/MariaDB
sudo systemctl status mysql --no-pager || sudo systemctl status mariadb --no-pager

# Quick connectivity test (will prompt for password if needed)
mysqladmin ping -h 127.0.0.1

3) Run a lightweight WordPress DB check

sudo -u www-data wp db check

If you’re moving from shared hosting to a VPS and you see a mix of DB and path/permission issues after cutover, follow a structured plan like this shared-to-VPS migration tutorial. The rollback and DNS steps matter as much as the file copy.

Reset admin access (safely) when wp-admin is inaccessible

If logins fail because of a plugin auth conflict, broken cookies, or a lost password, you can create a new admin user with WP-CLI.

Treat it as a temporary access hatch. Use it to regain control, then remove it.

cd /var/www/example.com/public
sudo -u www-data wp user create rescueadmin rescue@example.com --role=administrator --user_pass='Use-A-Long-Random-Password'

Once you’re back in, rotate credentials and delete the rescue account:

sudo -u www-data wp user delete rescueadmin --reassign=1

Fix HTTPS and site URL mismatches after a move (redirect loops, mixed content)

After a migration, redirect loops or mixed content usually trace back to incorrect siteurl/home values. Proxy headers that WordPress doesn’t recognize can also cause it.

1) Check current URLs

cd /var/www/example.com/public
sudo -u www-data wp option get home
sudo -u www-data wp option get siteurl

2) Set them explicitly

sudo -u www-data wp option update home 'https://example.com'
sudo -u www-data wp option update siteurl 'https://example.com'

3) Run a safe search-replace for mixed-content (with a dry run first)

sudo -u www-data wp search-replace 'http://example.com' 'https://example.com' --dry-run
sudo -u www-data wp search-replace 'http://example.com' 'https://example.com'

If the URL values are correct but SSL still fails at the web-server layer, fix certificates and TLS config first. HostMyCode’s HostMyCode VPS plans fit well when you need root access for Nginx/Apache TLS configuration and predictable performance under load.

For step-by-step certificate install and auto-renew, use this VPS SSL setup guide.

Use WP-CLI to run updates like a pro (and spot what will break before it breaks)

Once the site is stable, keep it that way. WP-CLI helps you turn surprise downtime into a controlled maintenance window.

1) See what’s pending

cd /var/www/example.com/public
sudo -u www-data wp core check-update
sudo -u www-data wp plugin list --update=available
sudo -u www-data wp theme list --update=available

2) Do a plugin update in batches (reduces blast radius)

# Update a single plugin first
sudo -u www-data wp plugin update woocommerce

# Then a small group
sudo -u www-data wp plugin update wordpress-seo contact-form-7

3) Use maintenance mode intentionally (so users see a friendly page)

sudo -u www-data wp maintenance-mode activate
sudo -u www-data wp plugin update --all
sudo -u www-data wp maintenance-mode deactivate

If you run WooCommerce, keep maintenance windows short. Also consider rate-limiting wp-login. A brute-force spike during an update can turn a slowdown into a full incident.

Quick checklist: the 12 commands you’ll reuse in real incidents

wp --info
wp option get home / wp option get siteurl
wp plugin list --status=active
wp plugin deactivate --all
wp theme activate twentytwentyfour
rm -f .maintenance
wp transient delete core_updater.lock
wp core verify-checksums
wp core download --force
wp db check
wp search-replace ... --dry-run
tail -n 80 /var/log/nginx/error.log (or Apache error log)

Summary: stabilize first, then make it repeatable

Get the site loading again first. Disable plugins, switch themes, clear update locks, and fix permissions.

After that, make recovery repeatable. Use verified backups, clean TLS, and an update process that doesn’t depend on wp-admin being reachable.

If you want a VPS that’s sized for WordPress, easy to scale, and comfortable for day-to-day admin work, start with a HostMyCode VPS. If you’d rather hand off patching, monitoring, and recovery help, choose managed VPS hosting so incidents don’t turn into multi-hour debugging sessions.

If you’re running WordPress on a VPS and updates keep surprising you, HostMyCode can help you get back to a calmer baseline. Pair a HostMyCode VPS with snapshots and tested restores, or choose managed VPS hosting for hands-on help with hardening, monitoring, and recovery.

FAQ

Can I use WP-CLI on shared hosting?

Sometimes. If your host provides SSH access and WP-CLI is installed, you can use it. Many shared plans don’t include shell access, which is one reason WordPress teams move to a VPS.

Should I run WP-CLI as root?

Avoid it. Root-owned files in wp-content commonly break future updates and uploads. Use the site owner user or the PHP-FPM pool user. Only use --allow-root as a last resort, and then fix ownership.

What if disabling plugins doesn’t fix the 500 error?

Switch to a default theme, then verify core checksums. If the error persists, check PHP-FPM status and your error logs. A PHP extension or memory limit issue can look like a WordPress problem.

How do I prevent this from happening again?

Keep verified backups, update in batches, and watch logs while you make changes. Practice restores periodically so you’re not learning the process during an outage.