The wp core verify-checksums command compares installed core files with the official checksum set for a WordPress version and locale. If the command, site option, downloaded package, deployment artifact, or filesystem reports the wrong identity, valid localized files can look modified and old files from a partial rollout can look malicious. Replacing files before confirming version and locale may erase evidence, introduce another mixed build, or create unnecessary downtime. This decision tree separates package-identity mismatch, partial deployment, approved local modification, unknown root file, and likely compromise before repair.
Use this when WP-CLI reports checksum failures after an update, on a localized WordPress installation, across several web nodes, or during malware triage.
Quick answer
Record wp core version, the intended deployment version, WPLANG, site locale, package source, artifact hash, and every origin node. Run checksums with the explicit expected version and locale when defaults are uncertain. Classify missing official files, modified official files, and unknown root files separately. If one version-locale pair passes and another fails, correct the package identity or deployment process before replacing anything. Preserve unexplained executable files for incident review.
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| Correct identity | Version and locale match | Official files pass |
| Wrong locale | Localized package checked as en_US | Mismatch explained |
| Partial rollout | Two origin versions | Node drift identified |
| Unknown PHP | include-root output | Preserved for triage |
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence | Verification |
|---|
| Freeze version and locale evidence | Record the version reported by WP-CLI, wp-includes/version.php, deployment manifest, container image, package lock, database upgrade state, and each independent origin filesystem. | Every origin reports the intended WordPress version, locale, package source, and clean or explained checksum result. |
| Run explicit checksum identities | Record WPLANG, site and user locale, downloaded distribution locale, translation package state, and whether the command uses explicit version and locale arguments. | Missing, modified, and unknown files each have a documented disposition and owner. |
| Classify every file result | Run the same checksum command on every node and separate modified official files, missing official files, and unknown files found with include-root. | Trusted replacement uses the confirmed release package without changing wp-content or deleting evidence. |
| Repair deployment or replace trusted core | Compare failures with release packages, deployment timestamps, rolling-update state, cache artifacts, approved customizations, host changes, and security alerts. | Database users, cron, must-use plugins, uploads, and public behavior receive separate post-repair review. |
What to check first
- Record the version reported by WP-CLI, wp-includes/version.php, deployment manifest, container image, package lock, database upgrade state, and each independent origin filesystem.
- Record WPLANG, site and user locale, downloaded distribution locale, translation package state, and whether the command uses explicit version and locale arguments.
- Run the same checksum command on every node and separate modified official files, missing official files, and unknown files found with include-root.
- Compare failures with release packages, deployment timestamps, rolling-update state, cache artifacts, approved customizations, host changes, and security alerts.
- Preserve suspicious files, replace core only from the confirmed trusted package, rerun checksums, and continue with wp-content, database, users, cron, and must-use plugin review.
Field notes
- Write the expected result before changing anything and keep one repeatable canary fixture for the full test window.
- Record exact versions and UTC timestamps because a cache purge, scheduled action, retry, or deployment can change the evidence between tests.
- Test the real browser and downstream record, not only an admin preview or isolated API call.
- Close the task only after the public workflow, server-side record, and relevant delivery or analytics system agree.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
wp core version
wp option get WPLANG
wp core verify-checksums --version=7.1 --locale=en_US
wp core verify-checksums --version=7.1 --locale=en_US --include-root
# Preserve unexplained files before any trusted replacement.
Why this usually happens
- A command infers a different locale than the package installed by the host or deployment tool.
- A rolling update leaves one origin or shared volume on the previous WordPress version.
- Core was edited directly and no approved artifact documents the change.
- Malware adds or modifies a plausible-looking PHP file in the installation root.
Decision rule
Correct package identity and deployment drift before interpreting a checksum mismatch as compromise. Treat unexplained executable changes and unknown root files as incident evidence until they are preserved and classified.
Production verification checklist
- Every origin reports the intended WordPress version, locale, package source, and clean or explained checksum result.
- Missing, modified, and unknown files each have a documented disposition and owner.
- Trusted replacement uses the confirmed release package without changing wp-content or deleting evidence.
- Database users, cron, must-use plugins, uploads, and public behavior receive separate post-repair review.
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Freeze version and locale evidence
- Run explicit checksum identities
- Classify every file result
- Repair deployment or replace trusted core
- Rerun integrity and persistence checks
Mistakes to avoid
- Changing production code, form fields, webhook endpoints, cache settings, or security limits before preserving the failing fixture and current configuration.
- Treating one clean dashboard status as proof even though the browser, PHP process, database, delivery provider, and downstream record have not been reconciled.
- Testing with a different form, role, locale, order state, entry shape, plugin version, or cache state than the workflow users actually reach.
- Leaving debug logs, temporary endpoints, broad permissions, copied secrets, or test notifications active after the verification window closes.
Questions teams ask during testing
Can I test this directly on production?
Read-only checks can be appropriate when access is controlled and output is redacted. Make a backup first, use a named canary record, test state-changing work on staging, define rollback, and schedule any production change for a monitored window.
How do I avoid a false positive?
Match the exact version, request path, form or order ID, role, locale, cache state, and integration path. Repeat the same fixture before and after the change, then compare the saved evidence rather than relying on memory.
What evidence should I keep?
Keep the UTC time, site and plugin versions, fixture ID, expected result, actual result, relevant logs, configuration snapshot, change made, rollback point, and final verification. Remove passwords, tokens, payment details, and personal data.
When should I bring in a specialist?
Escalate when checkout, payments, lead capture, security, customer email, accessibility, or several integrations are affected, or when the safest next step is unclear. A concise evidence packet reduces diagnosis time.
What to tell the client or owner
Give the owner a short evidence packet with the affected workflow, exact versions, UTC test time, fixture ID, expected and actual result, logs, change, rollback point, final result, owner, and next review date. Redact credentials and personal data before sharing it.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, have HandL WP classify the checksum failure safely.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references