DEV Community: Susumu Takahashi

Browser-based updates getting stuck on the "Confirm your admin email" screen — why Playwright stalls in wp-admin

Susumu Takahashi — Fri, 31 Jul 2026 02:02:59 +0000

On hosting environments without SSH access, the fallback is browser automation: Playwright logs into wp-admin and drives the plugin update screen directly. That works fine for months — until one day the script stops dead before it ever reaches the update screen.

Note: Playwright is a browser automation tool. It reproduces clicks a human would make, but as code.

What the "confirm your admin email" screen is

Since WordPress 5.3, wp-admin shows a periodic prompt — roughly every six months — asking the site owner to confirm they still have access to the registered admin email address. It's a core WordPress feature, not a plugin.

Is this still your address?
[ Yes, this is my address ]  [ I'll wait ]

A human clicking through wp-admin would just click "I'll wait" and move on. But a Playwright script written for a fixed sequence — log in, then navigate straight to the plugin update screen — has no branch for this extra screen. When it appears, the script stalls right there.

What actually happens

The login itself succeeds. The problem is the page it lands on: instead of wp-admin/index.php, the URL is wp-admin/options-general.php?adminhash=.... Whatever goto() call was supposed to take the script to the update screen next either gets redirected by this confirmation page, or the selectors it's waiting for never appear, and the script times out.

# Check for the confirmation screen right after login
if "adminhash=" in page.url:
    page.click("text=I'll wait")

Checking whether the post-login URL contains adminhash= is enough to detect that this screen has appeared.

Why the six-month cycle makes this hard to catch

The screen doesn't show up every time. WordPress core decides to show it only after enough time has passed since the last confirmation. That means automation that has been running cleanly for months can suddenly stop — and because it happens so rarely, tracing the cause back to this specific screen takes longer than it should.

The fix

Detect the "I'll wait" button and click it automatically as a standing step right after login, regardless of whether the screen actually appears. That way the same code path works whether the confirmation screen shows up or not.

def ensure_past_email_check(page):
    if "adminhash=" in page.url:
        page.click("text=I'll wait")
        page.wait_for_load_state("networkidle")

Calling this function immediately after every login means the twice-yearly surprise stops being a surprise.

Summary

Aspect	Detail
When it triggers	WordPress core decides enough time has passed since the last confirmation
Symptom	Post-login navigation lands on the confirmation screen, later steps time out
Detection	Check whether the post-login URL contains `adminhash=`
Fix	Auto-click as a standing step right after every login

Like Playwright strict-mode violations colliding with wp-admin's repeated selectors, this comes down to the same root issue: wp-admin doesn't always move in a straight line, and browser automation has to account for the screens it doesn't expect. As long as SSH isn't available and browser-driven maintenance is the fallback, detecting and stepping past these unplanned screens isn't optional. The same distrust of wp-admin also shows up in validating a version number scraped from the page before trusting it.

Why scheduled posts don't publish on time — inspecting WP-Cron with WP-CLI

Susumu Takahashi — Thu, 30 Jul 2026 00:28:15 +0000

A post scheduled to publish at a specific time doesn't go live when expected. A plugin's recurring email notification never arrives. This tends to happen on low-traffic sites, and there's a specific reason for it.

Note: WP-Cron is WordPress’s built-in scheduling system. It sounds like the OS-level cron daemon, but the underlying mechanism is quite different.

WordPress’s WP-Cron doesn’t work like a real OS cron daemon. On every page load, WordPress checks whether any scheduled task is past its due time and, if so, runs it. This is what's known as "pseudo-cron" — and its weakness is that nothing runs without a page visit. Schedule a post to publish at 3am on a site with little overnight traffic, and the publish task can sit unexecuted until the next visitor happens to load a page.

WP-CLI lets you look inside this otherwise invisible system and run exactly the task you need, right now.

Listing what's scheduled

wp cron event list

hook	next_run_gmt	recurrence
publish_future_post	2026-06-20 03:00:00	-
wp_version_check	2026-06-20 06:12:00	12 hours
wp_scheduled_delete	2026-06-21 00:00:00	daily

hook is the task's identifier, next_run_gmt is the next scheduled run time in UTC, and recurrence is the repeat interval. If publish_future_post is still listed despite its time having already passed, that confirms the task is overdue simply because no page load has triggered it yet.

Running a task right now

To trigger a specific task immediately:

# Run a specific hook right now
wp cron event run publish_future_post

# Run every overdue task at once
wp cron event run --due-now

--due-now finds every task whose scheduled time has passed but hasn't run yet, and executes all of them. Instead of waiting for a visitor to trigger the check, this one command runs the post publish, the email notification, or whatever else is pending.

Confirming WP-Cron itself is working

wp cron test

This checks whether the WP-Cron scheduler is functioning at all. On sites where wp-config.php has define('DISABLE_WP_CRON', true); set, the pseudo-cron mechanism is disabled entirely, and something else — a manual call or an external scheduler — has to call wp cron event run --due-now on a regular basis.

Checking available recurrence intervals

wp cron schedule list

name	display	interval (seconds)
hourly	Once Hourly	3600
twicedaily	Twice Daily	43200
daily	Once Daily	86400

Plugins that register custom intervals (e.g. every 15 minutes) show up here too. This is also where an unexpectedly frequent task can be spotted.

Switching to a real cron

Setting DISABLE_WP_CRON to true and calling WP-CLI from the server's actual crontab instead removes the dependency on page visits entirely — tasks then run at a guaranteed time.

# crontab example — every 5 minutes
*/5 * * * * cd /path/to/wordpress && wp cron event run --due-now > /dev/null 2>&1

The more common alternative — hitting wp-cron.php over HTTP with curl on a schedule — works too, but calling WP-CLI directly skips the HTTP overhead and avoids exposing wp-cron.php as a publicly reachable endpoint that has to be hit from outside the server.

Verifying after running

# Confirm the scheduled post is now published
wp post list --post_status=publish --orderby=date --order=DESC --posts_per_page=3

# Confirm no overdue tasks remain
wp cron event list

If publish_future_post no longer appears in the list, the corresponding post has already gone through its publish step.

Summary

What you need	Command
List scheduled tasks	`wp cron event list`
Run a specific task now	`wp cron event run <hook>`
Run every overdue task	`wp cron event run --due-now`
Confirm WP-Cron is working	`wp cron test`
List available recurrence intervals	`wp cron schedule list`

Knowing that WP-Cron is a page-visit-dependent pseudo-cron is what makes wp cron event list the first move when a scheduled publish doesn't go through. Like recovering from a wp-admin lockout or serialization-safe replacement, this is WP-CLI reaching past the admin dashboard to the mechanism actually running underneath it.

Locked out of wp-admin? Why WP-CLI works when `wp-login.php` doesn’t

Susumu Takahashi — Wed, 29 Jul 2026 00:19:18 +0000

A forgotten password, a security plugin that blocked your own IP by mistake, a plugin bug that turns the admin screen white — the causes vary, but the result is the same: you can’t log in to wp-admin.

Note: WP-CLI is a command-line tool for managing WordPress, invoked as wp. It operates directly on the server, without going through a browser.

This is exactly the situation where WP-CLI is useful. It works here because it never touches wp-login.php — it reads and writes the WordPress database and filesystem directly, so a broken login screen doesn’t affect it at all.

Why WP-CLI keeps working when wp-admin doesn't

A normal login follows the path: browser → wp-login.php → authentication → wp-admin. If anything along that path is broken — a plugin throwing a fatal error during authentication, a security plugin blocking your IP, a fatal error in the admin theme — the login itself can’t complete.

WP-CLI connects over SSH and reads/writes the wp_users and wp_options tables (and the filesystem) directly. The code in wp-login.php is never executed, so problems on that path don’t matter. This does require that SSH access itself still works — on most hosting providers, SSH is a separate access path from the admin dashboard, so it usually still works even when wp-admin doesn’t.

Scenario 1: Forgotten password

# List administrator accounts
wp user list --role=administrator --fields=ID,user_login,user_email

# Overwrite the password directly
wp user update 1 --user_pass='a-strong-new-password'

wp user update writes the new password directly to the database row — no password-reset email, no token, no waiting on a delivery that might land in spam or not arrive at all.

Scenario 2: A security plugin blocked your own IP

Login-attempt-limiting plugins occasionally misclassify legitimate activity as an attack and add the working IP to a block list.

# Deactivate the plugin responsible for the block
wp plugin deactivate <plugin-causing-the-lockout>

# Re-enable it later, after reviewing its configuration
wp plugin activate <plugin-name>

Deactivating the plugin also disables whatever block list or rate-limiting logic it was enforcing. If the cause isn’t clear, deactivate everything to isolate the problem:

# Stop all plugins to isolate the cause
wp plugin deactivate --all

# After confirming you can log in, re-enable them one at a time
wp plugin activate <plugin-a>
wp plugin activate <plugin-b>

Re-enabling one plugin at a time and checking login access after each step identifies exactly which plugin caused the lockout.

Scenario 3: No administrator account exists

A mistake during an offboarding cleanup can leave a site with no administrator account at all.

# Create a new administrator account
wp user create rescue_admin admin@example.com --role=administrator --user_pass='a-strong-password'

wp user create creates an administrator account immediately, with no email verification or plugin approval flow in the way. After recovery, either delete this emergency account or scope it down to the minimum permissions actually needed.

Scenario 4: A blank white screen in wp-admin

A PHP fatal error in a plugin frequently shows up as a blank white screen in wp-admin. Deactivating the offending plugin usually resolves it.

# After identifying the plugin from the error log
wp plugin deactivate <plugin-name>

If WP-CLI itself crashes while loading plugins, starting WP-CLI with --skip-plugins --skip-themes is the step that has to come first — none of the commands above will run until WP-CLI itself starts successfully.

What to verify after recovery

# Confirm no leftover emergency accounts remain
wp user list --role=administrator --fields=ID,user_login,user_email

# Confirm no plugins were left deactivated by mistake
wp plugin list --status=inactive

Any account or password created for emergency recovery should be removed or changed once the site is stable. Leaving it in place turns the fix itself into the next security gap.

Summary

Situation	Command
Forgotten password	`wp user update <ID> --user_pass=...`
Security plugin self-block	`wp plugin deactivate <name>` / `--all`
No administrator account left	`wp user create ... --role=administrator`
Blank screen from a plugin error	`wp plugin deactivate <name>`
WP-CLI itself won’t start	`--skip-plugins --skip-themes`

What every scenario above has in common is that WP-CLI never touches wp-login.php — it reads and writes the WordPress database directly. Like serialized-safe string replacement, where the s:N: byte-length prefix matters, or inspecting WP-Cron directly instead of waiting on a page visit, this is WP-CLI operating one layer below the admin dashboard — and that's exactly the layer that matters during a lockout.

Why phpMyAdmin migrations break plugin settings — and why `wp search-replace` doesn’t

Susumu Takahashi — Tue, 28 Jul 2026 00:13:40 +0000

After a domain migration or HTTPS switch, "all plugin settings are gone" or "Elementor layouts are broken" is a common outcome. The cause, in most cases, is running a string replacement against the WordPress database without accounting for PHP serialized data.

WordPress stores plugin configurations, custom field values, and widget settings in PHP’s serialized format. Standard SQL replacements — phpMyAdmin’s find-and-replace, raw UPDATE statements, sed on a .sql dump — rewrite the string value without updating the length metadata that serialization embeds alongside it. The result is a database that appears intact but returns false on every read of the affected values.

wp search-replace handles this correctly. Understanding why makes the pre- and post-execution steps more deliberate.

What PHP serialization stores alongside the value

A serialized entry in WordPress looks like this:

a:2:{s:4:"home";s:22:"http://example.com/top";s:5:"title";s:8:"My Site";}

The segment s:22:"http://example.com/top" means "a string of 22 bytes." The s:N: prefix records the byte length.

When a simple string replacement changes http://example.com to https://example.com:

Before: s:22:"http://example.com/top" (22 bytes)
After: s:22:"https://example.com/top" (23 bytes)

The s:22 stays unchanged even though the actual string is now 23 bytes. PHP’s unserialize() detects this mismatch and returns false. The plugin reads false instead of its configuration array and behaves as though the settings were never saved.

phpMyAdmin’s find-and-replace executes a SQL UPDATE at the storage layer. No PHP context exists there — it can’t know the column contains serialized data, and it doesn’t adjust the length prefix.

How `wp search-replace` handles it

wp search-replace operates at the PHP layer, not the SQL layer:

Reads each column value
Checks whether it’s serialized using is_serialized()
If serialized: calls unserialize() to expand it into a PHP array or object
Applies the string replacement to each value within the expanded structure
Calls serialize() on the result, recalculating all length prefixes
Writes the corrected value back

The length prefix is recalculated at step 5, so s:N: always reflects the actual byte count after replacement. The distinction is the same as the difference between overwriting a file directly versus going through an application that understands the file’s format.

Basic usage

# Backup before anything else — no exceptions
wp db export before-migration-$(date +%Y%m%d).sql

# Dry run: count how many rows would change, without writing anything
wp search-replace 'http://example.com' 'https://example.com' --dry-run

# Execute
wp search-replace 'http://example.com' 'https://example.com'

The --dry-run flag runs the full replacement logic internally but rolls it back, printing only the count of affected rows. Always run this first.

Scoping to specific tables

By default, every table in the database is scanned. For targeted replacements:

# Posts and custom fields only
wp search-replace 'http://example.com' 'https://example.com' wp_posts wp_postmeta

# Options table only (plugin settings, site URL, etc.)
wp search-replace 'http://example.com' 'https://example.com' wp_options

Running table by table is also easier to reason about when something goes wrong — you know exactly which scope was in progress.

The `--skip-columns=guid` case

The guid column in wp_posts is WordPress’s internal unique identifier for each post. It’s used as the item ID in RSS feeds. Changing guid causes RSS readers to re-import previously-seen posts as new entries.

wp search-replace 'http://example.com' 'https://example.com' --skip-columns=guid

For a new site or one that doesn’t publish RSS, this can be omitted. For an existing site switching to HTTPS with RSS subscribers, include it.

Verifying the result

# Confirm the site URL options are updated
wp option get home
wp option get siteurl

# Confirm nothing was missed — should return 0 replacements
wp search-replace 'http://example.com' 'https://example.com' --dry-run

A --dry-run returning 0 confirms the replacement is complete.

Summary

Method	Serialization-safe	Audit trail
phpMyAdmin find-and-replace	❌ Corrupts data	None
Raw SQL UPDATE	❌ Corrupts data	None
`wp search-replace`	✅ Safe	SSH log

If plugin settings are already corrupted from a phpMyAdmin replacement, restore the pre-migration backup with wp db import, then re-run the replacement with wp search-replace. There is no reliable way to repair corrupted serialized data in place — the backup taken before execution is the only recovery path.

For WP-CLI startup issues that can block this command from running, the --skip-plugins --skip-themes rescue method covers how to start WP-CLI when a broken plugin prevents normal startup. If the issue is being locked out of wp-admin entirely rather than WP-CLI itself, the lockout recovery guide covers password resets, plugin self-blocks, and missing administrator accounts.

Getting ready for WordPress 7.0 — three things to check now: PHP requirements, FSE migration, and editor extensions

Susumu Takahashi — Fri, 24 Jul 2026 00:23:51 +0000

Five failure patterns from past WordPress major upgrades ended with the observation that "the same structures will recur in some form in the next major (7.0 or 8.0)." This post applies that pattern knowledge to WordPress 7.0 specifically — not as a list of things that will happen, but as a preparatory checklist for what you can verify now.

This sits alongside the seven-item pre-flight checklist from W1 rather than replacing it. Think of it as the 7.0-specific supplement.

Item 1 — PHP minimum requirement increase (W3 pattern 3 again)

W3’s pattern 3 was "older plugins break with parse errors when the PHP minimum requirement is raised." This pattern repeats on every major upgrade cycle. WordPress 7.0 is expected to follow the same trajectory.

Background:

PHP 7.4 reached end-of-life from the PHP project in November 2022 (security support ended November 2023)
WordPress 6.6 requires PHP 7.2 minimum
WordPress 7.0 is expected to raise the minimum to PHP 8.0 or later

When this happens, sites running PHP 7.x will encounter plugins and themes that "worked fine before" but break with syntax or fatal errors after the upgrade. The mechanism is the same as past cycles — the plugin hasn’t updated its code to handle PHP 8.x stricter type handling, and the errors surface only at runtime.

What you can check now:

# Confirm the server&#8217;s PHP version
php -v

# List all plugins with their current version and update status
wp plugin list --fields=name,version,update,update_version --format=table

# Run a JSON output check — noisy output here means PHP warnings already leaking
wp plugin list --format=json

The pattern to watch for: plugins with an old "Tested up to" value and no updates in the past year. These are the highest risk candidates for PHP compatibility issues when the minimum requirement moves.

The post on PHP 8.2 Deprecated warnings leaking into WP-CLI JSON output covers a related symptom — even when PHP compatibility doesn’t cause a hard break, it can silently corrupt output in ways that are hard to trace. Worth having on the checklist alongside the version check.

Item 2 — FSE standardization and theme migration (W3 pattern 4 revisited)

W3’s pattern 4 was the FSE migration period in 6.0, where child theme customizations stopped working when switching to Block Themes. The 6.x cycle has steadily moved Block Themes toward the center — WordPress 7.0 is expected to continue that trajectory, with Classic Themes moving further toward "supported but not the primary path."

What this means in practice: sites still on Classic Themes don’t necessarily break when 7.0 arrives, but the friction accumulates. Theme updates, new block features, and plugin compatibility improvements increasingly target Block Theme architecture first. Classic Theme sites may find themselves in a "technically working but falling behind" position.

What you can check now:

Identify which sites use Classic Themes and which use Block Themes

  wp theme list --status=active --format=table
  # Check for a block-templates/ directory — its presence indicates a Block Theme

For sites on Classic Themes with deep customization: estimate what a migration to Block Theme would require
Identify sites where the migration cost is high enough that staying on Classic Theme is the right call for now (and document that decision)

The key discipline here: treat upgrading the WordPress core and migrating the theme architecture as two separate decisions. Doing both at once when a major version drops makes it impossible to isolate which change caused a problem. The core upgrade can happen on 7.0’s schedule; the theme migration happens on its own schedule.

Item 3 — Gutenberg Phase 3 and editor extension impact (W3 pattern 1 continuing)

W3’s pattern 1 was the 5.0 Gutenberg launch where editor extensions built for the Classic Editor stopped working. Gutenberg’s roadmap follows a phase structure — Phase 3 (collaborative editing, enhanced revision management, data library) continues that trajectory.

Collaborative editing changes the fundamental state management model of the editor. Third-party plugins that hook into editor internals — custom meta boxes, custom field UIs, sidebar extensions — face the same structural risk they faced in 5.0. The specific APIs differ, but the pattern is the same: a significant internal change in how the editor works causes adjacent extensions to lose their footing.

What you can check now:

List your active editor extension plugins

  wp plugin list --status=active --format=table
  # Manually identify editor-adjacent plugins: ACF, Pods, Meta Box, custom meta boxes, etc.

Check whether major vendors (ACF, Pods, Meta Box, WooCommerce block extensions) have announced Phase 3 compatibility
For plugins where no Phase 3 announcement exists yet, identify potential alternatives and flag them for follow-up

Note: "we don’t use collaborative editing" doesn’t mean you’re unaffected. Internal API changes in Phase 3 can affect plugins even on sites where the collaborative features themselves are never used. The dependency is on the editor internals, not the end-user feature.

Summary — what to do before 7.0 drops

Item	Check now	Act when
PHP requirement	`php -v` + plugin Tested-up-to audit	PHP 8.0+ minimum is confirmed
FSE / theme migration	Identify Classic vs. Block Theme per site, estimate migration cost	7.0 release announcement confirms Classic Theme support status
Editor extensions	List editor-adjacent plugins, check vendor Phase 3 status	Phase 3 lands in core

The common thread: starting this work after 7.0 is announced puts you under time pressure. Replacing plugins that don’t support PHP 8.x requires research, testing, and a migration window. Theme migration is a substantial project. Editor extension alternatives may need to wait for vendors to ship updates.

The step-by-step WP-CLI upgrade procedure from W4 pairs well with this list: once you’ve completed the pre-flight checks, the actual upgrade sequence follows the same pattern regardless of which major version you’re applying. And W2’s staged rollout approach — applying to lower-risk sites first before production — is especially useful when you have a mix of sites at different levels of readiness.

The W series in full

Post	Topic
W1 — What to check	Seven-item pre-flight checklist
W2 — When to apply	The x.0.1 rule and staged rollout
W3 — What can go wrong	Five failure patterns from past majors
W4 — How to run it	Step-by-step WP-CLI commands
W5 — Preparing for 7.0	Three things to check now ← this post
W6 — Verifying the result	7-step post-upgrade checklist

Pattern knowledge from W3 is most useful before the upgrade, not after. Knowing that PHP requirement increases follow a predictable pattern is only actionable if you run the plugin audit before 7.0 drops, not after the first site breaks. The preparation window is now.

Running a WordPress major upgrade step by step with WP-CLI — commands and checkpoints for each stage

Susumu Takahashi — Thu, 23 Jul 2026 00:00:41 +0000

The W series has covered what to check before a major upgrade, when to apply it, and what can go wrong. This fourth part covers the remaining question: how to actually run it. Once the preparation is in place and the timing is right, this is the command sequence to follow — one stage at a time, with a confirmation step at each boundary.

Why not use the admin dashboard Update button

The WordPress admin screen has an "Update All" button that runs core, plugin, and theme updates in a single operation. This is the approach to avoid for major upgrades.

The reason is loss of isolation. When core plus five plugins plus two themes update in one pass, any breakage afterward has multiple suspects and no clear way to narrow them down. The dashboard update also displays "Updated successfully" even when PHP warnings or non-fatal errors occurred during the process — making it easy to miss problems until they surface later.

WP-CLI lets you apply core, the DB migration, plugins (one at a time), and themes in separate steps, with a check between each one.

STEP 0 — Final checks before starting

Before touching anything, establish a baseline and take a backup.

# Confirm the current core version and what updates are available
wp core version
wp core check-update

# Export the database with compression
wp db export - | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz

# See which plugins have updates pending
wp plugin list --update=available --format=table

# See which themes have updates pending
wp theme list --update=available --format=table

wp core check-update tells you what the upgrade will move to before you start. Running it first also gives you a record of the pre-upgrade state in your session log.

The database backup taken here is the recovery point for the entire upgrade. If core update fails or something breaks in the DB migration step, this is what you restore from. Take it immediately before starting, not hours earlier.

STEP 1 — Update core in version steps

Jumping directly from 6.4 to 6.7 means several DB migration passes run back-to-back, and if something breaks you’re left trying to figure out which intermediate version caused it. Applying one version at a time keeps the problem space smaller.

# Specify the target version explicitly — don&#8217;t rely on "latest"
wp core update --version=6.5

# Run the DB migration immediately after core update
wp core update-db

# Verify core file checksums against the WordPress.org reference
wp core verify-checksums

Omitting --version= updates to the latest available, which skips the intermediate-version approach. For major upgrades, name the version explicitly.

wp core update-db aligns the database schema version with the code. Without it, WordPress may run the migration automatically when the admin screen loads — which works, but runs without any visible confirmation that it completed cleanly. Running it from WP-CLI gives you a clear success or failure signal.

wp core verify-checksums compares core files against the WordPress.org checksums for that version. On servers where files were previously modified directly via FTP, this catches discrepancies before they become confusing later. Worth running both before and after core updates.

After the core step: confirm that the admin dashboard loads and that the front page returns a 200 before moving on.

STEP 2 — Update plugins one at a time

With core confirmed stable, move to plugins. One plugin per update, with a check after each one.

# List plugins that have updates available
wp plugin list --update=available --format=table

# Update one plugin at a time
wp plugin update contact-form-7
# ... check the site ...
wp plugin update woocommerce
# ... check checkout flow ...
wp plugin update yoast-seo

A useful order: start with plugins that have a narrow blast radius (SEO, debugging tools, admin utilities), and finish with the high-stakes ones (e-commerce, forms, page builders, authentication).

Update earlier	Update later
SEO plugins, security scanners	WooCommerce, payment plugins
Admin utilities, debug tools	Page builders (Elementor, Beaver Builder)
Cache plugins	Authentication, multisite-related

W3’s failure patterns 2 and 3 — JS library version jumps and PHP minimum requirement changes — are most likely to appear during plugin updates. After updating any plugin with heavy JavaScript dependencies, open the browser console and check for JS errors before calling the step done.

If WP-CLI itself starts throwing errors or crashing after a plugin update, the --skip-plugins --skip-themes rescue flag lets you restart WP-CLI without loading plugins — useful for investigating the problem or rolling back without getting stuck in a broken plugin load loop.

STEP 3 — Update themes

After plugins are confirmed stable, update themes.

# Check which themes have updates
wp theme list --update=available --format=table

# Update the theme
wp theme update twentytwentyfour

If a child theme is in use, the parent theme update doesn’t touch the child theme files — but parent theme hook changes can break child theme behavior if the child overrides hooks that were renamed or removed. After any parent theme update, walk through the pages that use customized template parts.

W3’s pattern 4 — Classic Theme child theme customizations breaking when switching to Block Themes — is most likely to appear here if theme updates involve moving from one theme architecture to another. That’s a case where the theme update decision needs to be treated separately from the core upgrade decision.

Rolling back when something goes wrong

Have these commands ready before starting. Running the upgrade without knowing the rollback path in advance is the kind of setup where panic sets in under pressure.

Roll back core

# Force-reinstall a specific prior version of core
wp core update --version=6.4 --force

# Restore the database from the backup taken in STEP 0
wp db import backup_20260615_090000.sql.gz

--force installs the specified version even if it’s already installed — necessary when rolling back to the previous version that’s already recorded as the current one.

Roll back a plugin

# Force-install a specific prior version of a plugin
wp plugin install contact-form-7 --version=5.8.3 --force

Plugin rollback is covered in detail in the WP-CLI pinpoint rollback post. The version number to restore to is in the version column of wp plugin list.

When core has been rolled back, the situation is the same as the halt-after-core-rollback design: continuing plugin updates on an unstable core adds another variable to an already unclear state. Stabilize core first, then resume.

Summary

Command	When to use
`wp core check-update`	Baseline check before starting
`wp db export`	Immediately before core update (required)
`wp core update --version=X.X`	Core update with explicit version
`wp core update-db`	Immediately after core update (required)
`wp core verify-checksums`	Core file integrity check
`wp plugin update <name>`	One plugin at a time, check between each
`wp theme update <name>`	Theme update, visual check after
`wp core update --version=X.X --force`	Core rollback if needed
`wp plugin install <name> --version=X.X.X --force`	Plugin rollback if needed

Where W1–W4 fit together:

Post	Topic
W1 — What to check	Pre-upgrade checklist: 7 items
W2 — When to apply	The case for waiting for x.0.1
W3 — What can go wrong	Five failure patterns from past majors
W4 — How to run it	Commands and checkpoints for each stage ← this post
W5 — Getting ready for 7.0	Three things to check now: PHP, FSE, editor extensions
W6 — Verifying the result	7-step post-upgrade checklist

Running updates in stages isn’t a slower path — it’s the path that keeps each step reversible and each problem identifiable. When something breaks after a one-at-a-time update sequence, you know exactly which step caused it. That clarity is what makes the difference between a short investigation and a long one.

Three site-list UX improvements: instant completion feedback, error highlighting, and auto-deselect

Susumu Takahashi — Wed, 22 Jul 2026 01:06:06 +0000

The site-list visualization work has run across several posts: the blue pulse and green completion border, the marker-based running-site detection, and the three-state visual hierarchy. v1.6.8 added three more UX improvements to the same area. This post records the design decisions behind them.

All three share a common starting point: managing 10–20 sites in a bulk maintenance run that takes several tens of minutes, and making that time easier to follow without introducing new failure modes.

Improvement 1 — refresh the thumbnail and badge the moment a site finishes

Previously, thumbnails and the pending-plugin badge were only refreshed after the entire bulk run completed. If the first of ten sites finished early, its thumbnail stayed stale until all ten were done.

The fix: refresh only the completed site the instant its completion is detected. A new _refreshCompletedSitesNow function wires into the streaming-log loop. Each time a site-completion marker arrives, it:

Updates that site’s ?v=<mtime> to bust the thumbnail cache
Calls _invalidatePendingPluginCacheForSiteIds to partially invalidate and re-render the plugin badge

The key constraint: each refresh touches exactly one site and doesn’t interrupt the sites still running behind it.

Improvement 2 — highlight error sites in red for 24 hours

To make "which site had an error" visible at a glance after a run, a site-error CSS class was added — red border (#ef4444) plus a light red background (rgba(239,68,68,0.08)), applied to both the grid and list views. It follows the same pattern as the existing running / completed / pending classes. Status priority is running > error > completed > pending.

The error state persists for 24 hours via a _siteErrorStatus map with a completion timestamp. Twenty-four hours matches the green completion border from the earlier work — long enough to cover "what happened today." Starting a new maintenance run resets the previous error badge for those sites, so badges don’t carry over across separate sessions.

False-positive prevention — marker lines only

The most important design constraint in the error detection logic was avoiding false positives. Streaming logs contain many internal lines from the maintenance agent. If the detection is too broad, an innocent log line could trigger a red badge for a site that succeeded.

The fix: the agent emits exactly one conclusive marker line at the end of each site’s processing:

[site name] ✗ Maintenance result: ERROR
[site name] ✓ Maintenance result: OK

The front-end _detectSiteResultFromLog function only looks at lines containing Maintenance result: (or the Japanese equivalent). Every other line is ignored — the site stays green. This is the same conservative approach established in the streaming-log marker post: one unambiguous marker, no inference from surrounding context.

The tradeoff: a site whose marker line is never emitted stays green instead of showing an error. Missing an error badge is less harmful than showing a false-positive red badge, so the logic deliberately favors the cautious side.

Improvement 3 — auto-deselect after the run completes

After a multi-site maintenance run, the selected checkboxes remained checked. The next operation could unintentionally target those same sites again if the user forgot to clear them.

The fix: _finalizeMaintenanceRun — the shared teardown path for both standard maintenance and selective plugin updates — now automatically unchecks the sites that were part of the completed run (_runningSiteIdOrder). No toggle was added; auto-deselect is unconditional.

After a run, completed sites have a green or red border for 24 hours, so context about what ran is still visible through the color state. The checkbox doesn’t need to carry that history — the border does.

Wrap-up

These three improvements extend the site list from three states to four: waiting / running / completed / error. V33’s blue pulse and green border introduced running and completed. V44’s visual hierarchy formalized the three-level visual weight. Error is now an explicit fourth state with its own color and persistence.

The thread running through all three improvements is the same: when you can’t determine the right answer with certainty, default to the safer outcome. Partial refresh should not disturb other running sites. Error detection should not fire on ambiguous lines. Auto-deselect should not depend on the user remembering to clear. Each is a different problem, but the same instinct drove each solution.

Follow-up: Site list scrolls to top on every delete — fixing the missing keepScroll argument across 6 call sites

Why environment variables don’t suppress WP-CLI PHP Deprecated warnings — the phar + shebang path and a three-part structural fix

Susumu Takahashi — Tue, 21 Jul 2026 00:32:56 +0000

A previous post covered how to absorb PHP 8.2 Deprecated warnings from WP-CLI using a three-layer defense. The approach — prepending WP_CLI_PHP_ARGS to set error_reporting — works in many environments. But a case came up where Deprecated warnings wouldn’t disappear despite the same configuration. Tracing the cause revealed a structural reason why the environment variable never arrived. This post records that root cause and the three-part fix added in v1.6.8.

Why environment variables don’t arrive — the phar + shebang execution path

An agency reported that on Xserver, plugin list retrieval was failing across multiple sites (referred to here as "site A / site B") with a large volume of Deprecated messages. We reproduced the same behavior on our own Xserver setup (PHP 8.2.30, WP-CLI 2.7.1) and traced the execution path.

Xserver’s /usr/bin/wp is a phar binary. Inside, it starts with a #!/usr/bin/env php shebang, so the actual startup sequence looks like this:

shell → /usr/bin/wp (shebang: #!/usr/bin/env php)
                  ↓
        env locates php and starts it
                  ↓
        php loads the phar → WP-CLI runs

In this path, WP_CLI_PHP_ARGS is never read as a PHP startup option. WP_CLI_PHP_ARGS is supposed to let WP-CLI pass a -d flag to PHP, but when PHP itself is launched via shebang, control never reaches the point where WP-CLI can inject that flag into PHP’s invocation.

# doesn&#8217;t work — /usr/bin/wp on Xserver is a shebang-launched phar
WP_CLI_PHP_ARGS="-d error_reporting='E_ALL & ~E_DEPRECATED'" wp plugin list --format=json

# works — -d goes directly to the php binary
php -d error_reporting='E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED' /tmp/wp-cli-2.7.1.phar plugin list --format=json

We verified this against our production setup: with the first form, 407 Deprecated lines remained; with the second, 0.

Pillar A — detecting the php-direct path and injecting -d

The fix: inspect wp_cli_path for whether it’s a php-direct invocation, and if so, inject -d error_reporting immediately after the PHP binary.

inject_php_d_flag(wp_cli_path) in core/wpcli_json.py splits the path and checks the leading binary name.

If the binary is php, php8.2, php82, or any php* variant — inject -d error_reporting='E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED' right after it.
If the path is a bare wp or a direct .phar invocation — leave it as-is.

def inject_php_d_flag(wp_cli_path: str) -> str:
    parts = shlex.split(wp_cli_path)
    if not parts:
        return wp_cli_path
    binary = os.path.basename(parts[0]).lower().rstrip(".exe")
    if not (binary == "php" or binary.startswith("php")):
        return wp_cli_path  # bare wp / phar — leave unchanged
    flag = "-d error_reporting='E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED'"
    return shlex.join([parts[0], flag] + parts[1:])

Using os.path.basename ensures this works with both / and \ path separators — Linux on the server, Windows on the client.

Pillar B — locating the JSON range within noisy output

Even after suppressing Deprecated warnings, other noise (notices, warnings) can still appear in stdout. To handle that, we added a helper that extracts only the JSON portion from stdout rather than attempting to parse the entire string.

extract_json_from_wpcli_output(stdout) locates the first [ or { and the last ] or } in the output, and passes only that range to json.loads.

def extract_json_from_wpcli_output(stdout: str) -> Any:
    start = min(
        (stdout.find(c) for c in ("[", "{") if c in stdout),
        default=-1,
    )
    end = max(
        (stdout.rfind(c) for c in ("]", "}") if c in stdout),
        default=-1,
    )
    if start == -1 or end == -1 or start > end:
        return None
    return json.loads(stdout[start : end + 1])

PHP fatal errors and parse errors typically contain no JSON brackets, or contain them in positions that yield invalid JSON — so json.loads raises and the helper returns None. False positives stay low.

Pillar C — hardening nine json.loads call sites

The existing code had nine places calling json.loads(stdout) directly. These were unified to return a (parsed, raw) tuple, so failed parses still have the original stdout available for error handling and logging.

def parse_wpcli_json(stdout: str) -> tuple[Any, str]:
    try:
        return extract_json_from_wpcli_output(stdout), stdout
    except (json.JSONDecodeError, TypeError):
        return None, stdout

Keeping the raw output alongside the parse result means that when JSON decoding fails, there’s still something useful available — the actual stdout — without reconstructing it.

46 AST tests to prevent regression

Alongside the three pillars, we added tests/test_wpcli_deprecation_noise.py with 46 tests covering:

php detection boundary tests — php, php8.2, php82 trigger injection; wp, .phar do not
-d injection position tests — the modified command string has the flag in the correct position
7+ JSON locate cases — Deprecated noise mixed in, Fatal error only, clean JSON, empty string, and others
Structural static verification via AST — confirming that the existing json.loads call sites have actually been migrated to the tuple-return pattern

The V40 tests confirmed that the defense patterns ran correctly. These go one step further and use AST-based static analysis to verify that the code itself retains the intended structure — catching regressions that runtime tests alone would miss. Total test count went from 942 to 993.

Wrap-up

Environment-variable-based Deprecated suppression works when PHP is invoked directly, but doesn’t reach a shebang-launched phar like /usr/bin/wp on Xserver. The v1.6.8 fix addresses this in three layers:

Pillar A: parse wp_cli_path and inject -d directly when it’s a php-direct invocation
Pillar B: locate the JSON range in stdout rather than parsing the whole string
Pillar C: unify json.loads call sites to return (parsed, raw) tuples

When an environment variable "doesn’t work," the most productive first question is whether the path it’s supposed to reach even sees it. That structural diagnosis — rather than trying variations of the same configuration — is what led to this fix. For the original Deprecated noise and the v1.6.6 three-layer defense, the earlier post on WP-CLI PHP Deprecated noise covers the symptom side of the same problem.

When SSH to Xserver suddenly stops working, it's fail2ban — the official confirmation and a safer reconnection check

Susumu Takahashi — Sat, 18 Jul 2026 01:10:54 +0000

If you run WordPress maintenance for clients on Xserver, sooner or later you hit this: SSH was working fine this morning, and now your connection dies the instant it touches the host. No key change on your side, no obvious server-side incident. Just Connection closed by ..., and the silence deepens every time you retry.

A recent escalation to Xserver support gave us an official answer about what's actually going on. Worth writing down what an operator needs to know.

What the symptom looks like

In our observation, the symptom moves through two stages.

Lighter: Connection closed by [Xserver IP] — connection killed at the sshd layer before it's established
Heavier: ssh: connect to host ... port 10022: Connection refused — escalated to a firewall reject

If you notice the lighter stage early, recovery is still in sight. If you keep retrying, you move into the heavier stage, and waiting is the only viable option for a while.

What Xserver support told us

While escalating an unrelated issue, we asked Xserver about this "source-IP gets blocked" behavior. The official response:

When the attempt count exceeds the threshold, fail2ban temporarily restricts the source IP. The specific threshold, bantime, findtime, and whether manual unbanning is supported are kept confidential for security reasons.

So Connection closed / Connection refused from Xserver is the protection mechanism doing its job — not a server-side fault. The confidentiality of the threshold is reasonable (publishing it would help attackers), but two things you can operate with:

There is no manual-unban support channel (you have to wait it out)
Self-recovery happens within roughly half a day to a day (verified against our own production setup)

What triggers it

Even without intentional brute force, normal operational patterns can structurally trigger it. The most common one we see is having multiple SSH keys available to the agent while a maintenance tool repeatedly opens connections to Xserver.

paramiko and the OpenSSH client try the host key, ~/.ssh/id_*, and any keys in the SSH agent in sequence. With three keys registered, a single connection costs three to four auth attempts. When a maintenance tool fires those connections in parallel across multiple sites, the cumulative MaxAuthTries overruns add up fast enough to trip fail2ban's threshold.

The application-side fix (forcing look_for_keys=False / allow_agent=False in paramiko to constrain which keys are tried) is covered in the paramiko default that triggers IP blocks. This post stays on what to do once you're already blocked.

What to do once you're already blocked

Two real options.

1. Wait. No support channel for manual unban exists, so waiting half a day to a day is, in practice, the shortest path. If you have a scheduled maintenance window, tell the client "the server's protection mechanism temporarily restricted access; we'll resume after release." Calling it an "outage" misses the truth.

2. Switch your source IP. If you can reach the server from a different network (mobile WiFi, phone tethering, a fixed-IP service), recovery is immediate. We keep a domestic fixed-IP service on hand (Interlink My IP) and have confirmed that even while the primary line is blocked, ssh layer2024@layer2024.xsrv.jp works fine from the fixed IP. fail2ban operates per source IP, so different IPs go through normally.

A reconnection-check command that minimizes re-trigger risk

Right after recovery, what you actually want is a command that uses the fewest possible auth attempts to verify the line is back. If you have multiple keys registered and you just type ssh user@host, the cascading attempts can drop you right back into the same block.

ssh -i ~/.ssh/layer2024_xserver.key \
    -o IdentitiesOnly=yes \
    -o IdentityAgent=none \
    -p 10022 \
    layer2024@layer2024.xsrv.jp 'echo ok'

IdentitiesOnly=yes — only the key specified with -i is tried (no auto-tries on ~/.ssh/id_*)
IdentityAgent=none — keys held in the SSH agent are not tried at all
'echo ok' — checks the connection without opening a shell, then exits immediately

Make this your standard "first touch" command for Xserver. If your maintenance tooling carries the same posture (paramiko's look_for_keys=False / allow_agent=False), the structural cause stops recurring.

Wrap-up

If SSH to Xserver suddenly stops working, suspect fail2ban first, not a server fault. No manual-unban path exists; the choice is wait or switch source IPs. After recovery, run your first connection with IdentitiesOnly=yes / IdentityAgent=none so the verification itself doesn't re-trigger the block. For the application-side fix, paramiko's default behavior covers the design angle.

The half-second of "did the server break?" panic settles a lot faster once you can name the protection mechanism by sight. It's a small piece of operational vocabulary that meaningfully changes how an agency carries the surprise.

Five failure patterns from past WordPress major upgrades — what 5.0 Gutenberg through 6.0 FSE taught maintenance teams

Susumu Takahashi — Thu, 16 Jul 2026 23:33:30 +0000

With the pre-upgrade checklist of seven items and the calibration framework for when to apply, we've covered preparation and timing for WordPress major upgrades. The third installment is "what can go wrong" — the failures that actually happened in past majors, organized into five patterns.

The examples are tied to specific releases (5.0 / 5.6 / 6.0), but the point is that the same structural patterns repeat in new majors. Carrying these as types in your head pays off when 7.0 or 8.0 lands and you need to triage fast.

Pattern 1 — "Editor-adjacent UI extensions" disappear en masse (5.0 Gutenberg)

The most operationally impactful incident when WordPress 5.0 standardized the block editor (Gutenberg).

Symptom: Custom meta boxes assuming the classic editor (TinyMCE), custom field UIs, and third-party plugin editor extensions stopped working simultaneously. Content itself wasn't broken — but the editing UI vanished.

Cause: Code written against the classic editor's DOM and hooks loses its anchor points in Gutenberg's React-based UI. Simple add_meta_box() extensions kept working, but anything hooked directly into a TinyMCE instance fell over completely.

The fix pattern: Run the Classic Editor plugin to preserve the old UI temporarily, while planning the migration to Gutenberg-aware forks or replacement plugins. "Inventory editor-adjacent plugin dependencies before applying the upgrade" makes the migration scope visible up front.

What this incident demonstrates is that the flagship feature of a major release maximizes impact on the surrounding ecosystem. The same structure will repeat with any future "new editor feature" or "new admin UI."

Pattern 2 — A wholesale JS library bump triggers cascading breakage (5.6 jQuery 3.x)

When WordPress 5.6 jumped jQuery from the 1.x series to 3.x.

Symptom: Front-end JS goes dark. Broadly-used jQuery plugins for sliders, modals, form validation, etc. stop working, and the site's "dynamic parts" break across themes and plugins.

Cause: jQuery 3.x removes APIs that had been deprecated for years — $.live(), parts of $.bind() semantics, parts of the $.ajax Promise interface. Code depending on them doesn't error syntactically — it fails silently at runtime.

The fix pattern: Bring in jquery-migrate to provide a compatibility layer for the deprecated APIs, then refactor JS based on the console warnings it logs. Opening the browser dev-tools Console while clicking through staging becomes a required step.

The lesson here is that "the front-end isn't visible from an admin check." That's why the staging verification in W1 includes "do the critical front-end pages render correctly" — exactly this pattern is why.

Pattern 3 — Raised PHP minimum trips syntax errors in old plugins

Unlike the previous two, this is a general pattern that recurs across many majors, not tied to a specific release. The notable boundaries are PHP 7.4 → 8.0 and PHP 8.1 → 8.2 (the dynamic property deprecation).

Symptom: After the upgrade, specific plugins show as "deactivated" in the admin, or the site is white-screened with a Fatal error. The error log shows PHP Parse error or PHP Fatal error: Cannot use ... in write context.

Cause: Each new PHP version tightens syntax and the type system. A plugin's "slightly old code" can no longer be parsed under newer PHP. Or, a warning becomes a deprecation, and depending on display settings, looks fatal.

The fix pattern: Before the upgrade, run wp plugin list --format=json against the new PHP environment and verify the JSON comes back clean (alongside the trap of operational tools breaking from deprecated noise). Plugins with old "Tested up to" deserve replacement evaluation prior to the major upgrade.

What's particularly painful is the "PHP raised, but old plugins kept" in-between state. The PHP version may satisfy WordPress's minimum while the plugin lags behind PHP's new version — and the site still breaks.

Pattern 4 — Theme structure changes invalidate child-theme customizations (6.0 FSE)

When Full Site Editing (FSE) matured in WordPress 6.0.

Symptom: Existing Classic Theme customizations don't break on the 6.x upgrade itself — but the moment you switch to a Block Theme, the template-parts/*.php overrides your child theme provided stop being effective. The traditional template hierarchy (header.php, footer.php) is replaced by HTML templates (block-templates/*.html) in Block Themes.

Cause: Block Themes have a fundamentally different file structure from Classic Themes. The child-theme override mechanism relies on the old filename conventions, so it can't reach into the Block Theme's HTML template structure.

The fix pattern: Two paths — keep the Classic Theme for the foreseeable future, or commit to a child-theme redesign as part of migrating to a Block Theme. "Should we migrate the client's theme?" and "Should we upgrade WordPress?" become separate decisions.

The takeaway is that major releases create transition periods. When two systems coexist — Classic Theme and Block Theme — having a documented operational rule for "which one do we stay on" pays off.

Pattern 5 — Tiny internal API tweaks quietly break external integrations

The first four are relatively easy to notice. This last one is the slowest to discover.

Symptom: Everything looks normal immediately after the upgrade. Days or weeks later, "the API integration where an external system POSTs into WordPress has stopped working" comes to light. Auto-posting and auto-updates from CRMs, core business systems, or internal workflows fail silently with no error log entries.

Cause: REST API scope changes, subtle authentication tweaks, CORS header expectations, X-WP-Nonce lifetime changes — small items buried in the "Developer Notes" section of the official release notes that break external auth flows.

The fix pattern: The one-week soak in staging from W2 exists exactly to catch this pattern. The failure mode doesn't show up in an immediate post-upgrade admin click-through — it only surfaces with time and real traffic. Run Site Health's Loopback test, let cron jobs cycle, leave staging running for a stretch and watch.

For sites with external integrations, "every integration's auth path, tested end-to-end" must be on the major-upgrade checklist.

Closing — knowing the patterns lets you handle future failures

Stacking the five patterns shows the common axes:

Editor and UI surfaces concentrate breakage when flagship features ship (Pattern 1)
JS / PHP major version dependencies trigger cascading failures (Patterns 2 & 3)
Structural pre-condition changes create a "transition period" with two systems coexisting (Pattern 4)
Silent breakage only surfaces with time (Pattern 5)

These structures will recur in some form in the next major (7.0 or 8.0).

The full series relationship
W1 = what to verify (seven-item pre-flight checklist)
W2 = when to apply (five calibration axes)
W3 = what can go wrong (five typical failure patterns) ← this post
W4 = how to run it (WP-CLI commands and checkpoints for each stage)

Aligning the whole upgrade lifecycle as "preparation → timing → risk prediction" sharpens operational decisions. When WordPress 7.0 drops, starting with "which of the five past patterns does this match?" tends to point you at the right response faster.

The "types" here aren't visible when you only operate one site. Maintaining a portfolio of sites, you tend to meet at least one of them in some form on every major. Moving from reactive triage per incident to predictive pattern matching — that shift is, in my view, the core of making maintenance work sustainable as a practice.

Don't apply WordPress major releases on day one — the "x.0.1 rule" and a calibration framework

Susumu Takahashi — Thu, 16 Jul 2026 00:10:26 +0000

The companion to the seven things to check before a WordPress major upgrade is the question that comes right after: when do you actually apply it?

A new WordPress major drops today. Do you ship it to production tonight? Tomorrow? In a week? Hold for the next scheduled monthly maintenance? This call tends to live in tribal knowledge, but a few clear axes combined together give you a calibration framework you can apply every time without re-deciding from scratch. Here are five axes worth using.

Premise — majors are not security patches

The first thing to anchor: a major upgrade is not a security patch.

WordPress ships security fixes via minor releases (6.4.1 → 6.4.2, 6.5.0 → 6.5.1 — the second-digit bumps). Those are same-day apply by default. Major releases (6.4 → 6.5, eventually some 6.x → 7.0) carry new features and API changes; they aren't released to be applied immediately for security reasons.

Without this distinction, the felt urgency of "we have to apply this for security" pushes you to rush majors that should wait. Minors immediately, majors by judgment — that separation is the first rule worth writing down.

Axis 1 — wait for `x.0.1`

For essentially every major release, x.0.1 (the first patch release) lands within 1–3 weeks and absorbs the critical bugs that surfaced after launch.

Past examples have included things like "the admin goes white under specific settings," "a particular theme breaks the block editor," "DB migration stalls in specific environments." Nobody hit these on launch day; they emerged as the world started using it for days or weeks.

Just waiting for x.0.1 instead of x.0 sidesteps most of those launch-window bugs. For the first few weeks after a major lands, the world's WordPress installations are effectively running the beta test. Being downstream of the people who hit the mines is the rational position for a maintenance practice.

Axis 2 — wait until major plugin vendors update "Tested up to"

The thing that breaks most after a major upgrade is, almost always, plugin compatibility. Theme compatibility follows, but plugins dominate the impact column.

What to watch is whether major plugin vendors have declared support. Concretely:

ACF (Advanced Custom Fields)
WooCommerce (mandatory if you're touching commerce)
Yoast SEO / Rank Math (SEO)
Elementor / Beaver Builder (page builders)
WPML / Polylang (multilingual)
Wordfence / iThemes Security (security)

Until these heavyweight plugins bump Tested up to in their readme.txt or publish a "we support it" announcement on their blog, production-side adoption stays paused. If the major plugins haven't caught up, the WordPress release hasn't 'aged' yet is the call we make.

Axis 3 — soak in staging for a week

The staging step from W1 has an extra job for majors: catch the bugs that surface over elapsed time, not just the ones visible right after upgrade. Specifically:

wp-cron continues to run (daily / weekly jobs fire on schedule)
Email delivery hasn't quietly broken (comment notifications, contact forms)
Caches haven't corrupted into stale content
Image / OGP generation doesn't fail under time-delayed conditions

These don't show up in "upgrade and click around the admin for ten minutes." They need at least a week of natural operation. Soak the staging site for a week; if the error logs aren't accumulating anything strange, you've earned the right to consider production.

Axis 4 — site risk profile

"When to apply" also shifts with the site's risk profile. A rough three-tier breakdown:

Profile	Examples	Recommended wait
High risk	Commerce, booking, membership, LMS	After `x.0.2` + all major plugins confirmed + 2 weeks of staging
Medium risk	Mid-size corporate, blog/media, contact forms	After `x.0.1` + major plugins confirmed + 1 week of staging
Low risk	Static corporate, internal portal, experimentation	After `x.0.1` + a few days of staging

Commerce and booking directly translate "dropped orders = lost revenue," so the longer wait pays for itself. A static corporate site might tolerate a minor layout glitch with no immediate business impact, so a more forward posture is fine.

Avoiding "all sites upgrade on the same day" and applying in waves by risk profile is one of the better distribution strategies for a maintenance practice.

Axis 5 — alignment with the client contract / SLA

Last axis is contractual. If you have monthly recurring maintenance contracts, aligning major upgrades to the next monthly window makes contractual sense — it's the cleanest billing and scope story.

Check each release for "is there an emergency-update need that exceeds monthly-maintenance scope?" If no, fold it into the next month. If yes (rare cases where a critical security fix rides on the major), carve it out as a separate engagement with its own scope and price.

Writing this boundary into the contract upfront reduces the friction between "apply this now" and "let's wait" expectations across clients, and the operational rhythm stays steady.

Framing — the cost of waiting vs. the cost of charging in

Stacking five axes can read as "we never do anything," but waiting has real costs:

The window without new features is longer
When you do upgrade, the delta accumulates with simultaneous minor updates
You drift closer to old-version support cutoffs

Charging in has its own:

Outages → client trust erosion
Recovery cost (including after-hours engineering)
In some cases, direct business continuity impact

Calibrating between those, against each site's risk profile, is the heart of "when to apply." There's no closed-form rule, but the five axes together give you a decision skeleton that doesn't drift.

When a major upgrade does turn into an incident, you may need to invoke a post-rollback halt path on the core — and remembering that a rushed upgrade can create extended recovery work makes the few-week wait for x.0.1 look, in long-term maintenance ROI terms, very nearly always in the black. Read together with five failure patterns — which turns past incidents into types — and the calibration sharpens further.

Seven things to check before a WordPress major upgrade — before "patch what breaks after" becomes a disaster

Susumu Takahashi — Wed, 15 Jul 2026 00:37:22 +0000

WordPress major version upgrades (5.x → 6.x, and eventually 6.x → 7.x) are a different animal from minor releases. Minor releases (like 6.4.1 → 6.4.2) are mostly bug fixes with low compatibility risk. Majors land API deprecations, raised PHP minimum requirements, and core block replacements all at once — and those things hit operations hard.

The "just hit Update in the admin and patch whatever breaks" workflow can survive on a single personal site, but it tends to fall apart under multi-site maintenance — simultaneous failures across sites overwhelm root-cause triage. This post collects the things worth verifying before you run a major upgrade, as a seven-item checklist.

1. Has the minimum PHP version been raised?

Major WordPress releases sometimes raise the minimum supported PHP version (6.6 lifted it to PHP 7.2.24, and a future 7.0 will very likely require PHP 8.x). What matters operationally isn't just the server's PHP version and WordPress's stated minimum — it's the intersection with the PHP versions your plugins and themes actually run on.

You can usually upgrade your server's PHP, but older themes and plugins not running on new PHP isn't rare. A subtle failure mode here: traps like PHP 8.2+ deprecated warnings leaking into older WP-CLI JSON output, where nothing visibly errors but your operational tooling silently breaks. Before upgrading, run wp plugin list --format=json on the production PHP environment and verify you're getting clean JSON. That one check catches a lot of post-upgrade pain.

2. Audit "Tested up to" for every plugin

Each plugin's readme.txt carries a Tested up to: X.X line — the developer's declaration of the highest WordPress version they've actually tested against. It's the first signal for major-upgrade compatibility audits.

WP-CLI gives you the inventory in one shot:

wp plugin list --fields=name,version,update_version,update --format=table

Plugins where "Tested up to" is old AND no updates in the last year deserve scrutiny. Active development may have stopped, which means no fix is coming when the major upgrade breaks them. Better to identify replacement candidates pre-upgrade than to scramble post-upgrade.

3. Theme compatibility — child themes and deep customizations

Themes feel the major upgrade too. Watch especially for:

Block editor APIs (5.x→6.x landed massive API changes here)
Customized child themes (parent theme updates, but child theme hooks stay on the old API)
Page-builder plugins and their version requirements

In client work, "the theme is too old to upgrade PHP" is a regular blocker. Theme-side constraints that effectively pin WordPress to an older version need to surface at planning time, not after you've already started the upgrade.

4. Database backups — keep at least three generations

Major upgrades often involve database migrations. WordPress migrations are idempotent in principle, but recovering from one that dies halfway is unpleasant. Take a full backup before running the upgrade, and keep the latest, one before, and one further back — three generations is the safe floor.

# DB export (compressed)
wp db export - | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz

# wp-content if you want the full bundle
tar czf wp-content_$(date +%Y%m%d_%H%M%S).tar.gz wp-content/

For large sites, an SSH disconnect mid-export can leave a partial .sql lying around. Verify completion before moving on.

5. Run it in staging first

Hitting production with a major upgrade — even on a single site — is something to avoid. Mirror production into staging, upgrade there first, eyeball the front end, click through the admin, check WP-CLI, walk through the top plugins' admin screens. Then production.

Some hosts ship a staging feature out of the box; that's usually the fastest path. Otherwise an rsync to a separate directory on the same server (with a separate DB import) does the job.

The minimum verification list for staging:

Admin opens; post editor renders correctly
Critical front-end pages render normally
Forms and other dynamic features actually work
wp plugin list returns clean output

6. Use WP-CLI to stage the updates (skip the admin's one-click)

The admin's "Update" button is designed to fire everything at once. Core, plugins, themes — all in a batch. When something breaks, you can't tell which one broke it. That's particularly damaging on major upgrades.

WP-CLI lets you do core / plugins / themes separately, in order:

# 1. Core first
wp core update --version=6.7

# 2. DB migration
wp core update-db

# 3. Plugins one at a time
wp plugin update <plugin-name>

# 4. Themes the same way
wp theme update <theme-name>

Passing --version= keeps you from jumping multiple versions at once. From 6.4 to 6.7, going 6.5 → 6.6 → 6.7 instead of a direct jump makes it much easier to localize whatever goes wrong to a specific step.

A related gotcha: there are scenarios where WP-CLI itself fails to bootstrap because of a broken plugin. Knowing the --skip-plugins --skip-themes rescue flags pays for itself the first time WP-CLI refuses to start after an upgrade.

7. Write the rollback procedure down — before you upgrade

Last item: write down how you'll roll back before you start. "I'll just google it if I need to" doesn't survive contact with reality — under outage stress you don't want to be researching, you want to be executing a known procedure.

Minimum contents:

DB restore command (using the backup from step 5)
Filesystem restore command (the exact tar xzf)
WP-CLI command to roll core back one version:

  wp core update --version=6.6 --force

Per-plugin rollback (the approach from pinpoint rollback with WP-CLI):

  wp plugin install <plugin-name> --version=X.X.X --force

The act of writing this down surfaces missing prep — you'll find a missing backup, a server where WP-CLI isn't installed, the wrong privileges. The document itself doubles as a pre-flight check.

Closing — ten minutes before saves hours after

Listing seven items makes the upfront work look heavy, but with practice the pre-upgrade check takes 10–15 minutes total (the next question — "when do you actually apply it?" — is covered in the x.0.1 rule and a calibration framework, and the failures that actually happened in past majors are in five failure patterns). Charging in without it and recovering from a broken site is a multi-hour to half-day project. With more than a handful of sites under maintenance, that ratio dominates your operational economics.

"Just patch whatever breaks" works for a hobby site. It doesn't work as a maintenance offering. Keep one checklist by your side, walk down it every time a major upgrade comes around — that alone bends the incident rate down measurably.

DEV Community: Susumu Takahashi

Browser-based updates getting stuck on the "Confirm your admin email" screen — why Playwright stalls in wp-admin

What the "confirm your admin email" screen is

What actually happens

Why the six-month cycle makes this hard to catch

The fix

Summary

Why scheduled posts don't publish on time — inspecting WP-Cron with WP-CLI

Listing what's scheduled

Running a task right now

Confirming WP-Cron itself is working

Checking available recurrence intervals

Switching to a real cron

Verifying after running

Summary

Locked out of wp-admin? Why WP-CLI works when `wp-login.php` doesn’t

Why WP-CLI keeps working when wp-admin doesn't

Scenario 1: Forgotten password

Scenario 2: A security plugin blocked your own IP

Scenario 3: No administrator account exists

Scenario 4: A blank white screen in wp-admin

What to verify after recovery

Summary

Why phpMyAdmin migrations break plugin settings — and why `wp search-replace` doesn’t

What PHP serialization stores alongside the value

How wp search-replace handles it

Basic usage

Scoping to specific tables

The --skip-columns=guid case

Verifying the result

Summary

Getting ready for WordPress 7.0 — three things to check now: PHP requirements, FSE migration, and editor extensions

Item 1 — PHP minimum requirement increase (W3 pattern 3 again)

Item 2 — FSE standardization and theme migration (W3 pattern 4 revisited)

Item 3 — Gutenberg Phase 3 and editor extension impact (W3 pattern 1 continuing)

Summary — what to do before 7.0 drops

The W series in full

Running a WordPress major upgrade step by step with WP-CLI — commands and checkpoints for each stage

Why not use the admin dashboard Update button

STEP 0 — Final checks before starting

STEP 1 — Update core in version steps

STEP 2 — Update plugins one at a time

STEP 3 — Update themes

Rolling back when something goes wrong

Roll back core

Roll back a plugin

Summary

Three site-list UX improvements: instant completion feedback, error highlighting, and auto-deselect

Improvement 1 — refresh the thumbnail and badge the moment a site finishes

Improvement 2 — highlight error sites in red for 24 hours

False-positive prevention — marker lines only

Improvement 3 — auto-deselect after the run completes

Wrap-up

Why environment variables don’t suppress WP-CLI PHP Deprecated warnings — the phar + shebang path and a three-part structural fix

Why environment variables don’t arrive — the phar + shebang execution path

Pillar A — detecting the php-direct path and injecting -d

Pillar B — locating the JSON range within noisy output

Pillar C — hardening nine json.loads call sites

46 AST tests to prevent regression

Wrap-up

When SSH to Xserver suddenly stops working, it's fail2ban — the official confirmation and a safer reconnection check

What the symptom looks like

What Xserver support told us

What triggers it

What to do once you're already blocked

A reconnection-check command that minimizes re-trigger risk

Wrap-up

Five failure patterns from past WordPress major upgrades — what 5.0 Gutenberg through 6.0 FSE taught maintenance teams

Pattern 1 — "Editor-adjacent UI extensions" disappear en masse (5.0 Gutenberg)

Pattern 2 — A wholesale JS library bump triggers cascading breakage (5.6 jQuery 3.x)

Pattern 3 — Raised PHP minimum trips syntax errors in old plugins

Pattern 4 — Theme structure changes invalidate child-theme customizations (6.0 FSE)

Pattern 5 — Tiny internal API tweaks quietly break external integrations

Closing — knowing the patterns lets you handle future failures

Don't apply WordPress major releases on day one — the "x.0.1 rule" and a calibration framework

Premise — majors are not security patches

Axis 1 — wait for x.0.1

Axis 2 — wait until major plugin vendors update "Tested up to"

Axis 3 — soak in staging for a week

Axis 4 — site risk profile

How `wp search-replace` handles it

The `--skip-columns=guid` case

Axis 1 — wait for `x.0.1`