Common Issues

Loopback is blocked#

Symptom: Preflight shows the loopback check as failing, and runs are skipped.

Cause: Update Doctor has to request its own pages. Some hosts, firewalls, basic-auth protection, or a wrong site URL block that. A blocked loopback is never read as a broken site, so the run is refused instead.

Fix:

1. Open the Dashboard and read the preflight message.
2. Check that your Site Address and WordPress Address resolve from the server itself.
3. Ask your host to allow the server to request its own domain, or add the domain to the server’s hosts file.
4. Remove any basic-auth or IP restriction that blocks requests from the server’s own IP.
5. Press the re-check button on the Dashboard.

The site is in maintenance mode#

Symptom: A run waits and nothing is checked.

Cause: WordPress is in maintenance mode, which happens during an update. Update Doctor never reads a maintenance page as a broken site, so it waits.

Fix: Wait a few minutes. WordPress clears maintenance mode at the end of its update. If a .maintenance file was left behind by an interrupted update and is older than ten minutes, it is ignored. Stuck runs resume on their own through WP-Cron.

The probe user conflicts or logged-in pages are unverified#

Symptom: Logged-in pages show unverified, or turning on Logged-in checks fails.

Cause: Logged-in checks use a read-only user called “Update Doctor probe” with the updoc_probe role. If a different user already uses the probe login or email, Update Doctor refuses to reuse it and reports a probe user conflict. A security plugin that blocks loopback requests can also leave logged-in pages unverified.

Fix:

1. Rename or remove the other user that holds the probe login or email.
2. Turn Logged-in checks off and on again on the Key pages tab so the probe user is created.
3. Make sure no security plugin blocks loopback requests that carry the probe cookie.

AI is not ready#

Symptom: The diagnosis shows only the rules finding, and the AI status says not ready.

Cause: No AI provider is connected, the provider is not supported, AI diagnosis is off, or the monthly token budget is used.

Fix:

1. Open Settings > Connectors (WordPress core) and add a provider and key.
2. Check that AI diagnosis is on in Update Doctor’s AI tab.
3. Check the monthly token budget. Raise it, or set it to 0 for no limit.

Everything else keeps working without AI.

An agent gets a 403 when it approves something#

Symptom: An agent or script using an Application Password gets a 403 from the update-doctor REST routes.

Cause: This is deliberate. The REST routes serve only the admin screens: they need the login cookie and a valid nonce, and refuse Application Password logins and any other kind of login. No ability can approve, reject, undo or restore.

Fix: Have an agent read, propose and diagnose with the abilities. A person approves in wp-admin, or in WP-CLI with wp update-doctor approve <id> --user=<user>.

A run ended “restored” but I think the update was fine#

Open the run report and read the failing finding. If it is structure_changed on a page whose layout changes between visits, lower the structure threshold on the Safety tab. Add required text to your key pages to make the checks more exact. You can set When checks fail to Ask me first while you tune.

Approving says another update is running#

Symptom: Approving a restore, a plugin deactivation or a retry says that another update is already running, and the proposal stays waiting.

Cause: These actions change files or plugin activation, so they wait until the active update run has finished.

Fix: Wait for the run to finish (watch it on the Dashboard), then approve again.

A run seems stuck#

Symptom: A run has not moved for a long time.

Cause: A request was cut short. Stuck runs resume on their own through WP-Cron, and a step that is cut short three times gives up: before the update the run ends with an error and nothing was changed.

Fix: Wait for the hourly resume. If the run is still stuck, end it with wp update-doctor run <id> --abandon. While it is at the update, verify or restore step this needs --force; check the site and the run’s snapshot first.

A run was skipped#

Open the run and read the reason: preflight failed, the item is held, the release is inside the cooldown, the update needs a newer PHP or WordPress than your site runs, or there is no usable baseline.