Troubleshooting the worker
The states the platform reports about a worker it cannot reach, what each means, and what to change.
The platform never reports a site as merely "inactive". Every time it cannot reach a worker it establishes where the connection broke — does the site's name resolve, does the site answer, does WordPress answer, is the plugin active and complete, does it accept the credential — and reports that. The site's Health page shows it, with an instruction where a person is needed.
| State | What was found | What to do |
|---|---|---|
| DNS error | The site's name does not resolve. | Check the domain's DNS; check the address the site was added with. |
| SSL error | The certificate is invalid, expired, or for another name. | Renew or correct the certificate on the host. |
| Timeout | The site did not answer in time. | Usually the host; the platform asks again on a widening schedule. Persistent timeouts are a host performance problem. |
| Connection refused | Nothing answered on the port. | The web server is down or the address is wrong. |
| Blocked by a firewall | A firewall (the provider is named) answered instead of the site. | Allow the platform's address as instructed on the Health page. Since 2.3.0 the site keeps reporting and taking its work meanwhile. |
| Plugin inactive | WordPress answers, but the worker is not active. | Activate the worker, or reinstall it if it is gone. |
| Route missing | The worker is active but incomplete. | A partial install or an old version; reinstall the current release. |
| Authentication failed | The site refused the workspace token — and whether another plugin took the credential first is noted. | If a JWT plugin is involved: exclude the worker's wpocto/v1 namespace in that plugin, or bring the site to 2.3.0. Otherwise the token on the site is not the workspace's; paste the current one. |
| Worker error | A PHP error on the site. | Read the error the page shows; an error in the worker itself is recovered as Recovery describes. |
| HTTP error | Another HTTP status that is not a WordPress answer. | Read the status; often a host's maintenance or error page. |
| Unknown | A shape none of the above fit. | Report it; the platform records what it saw. |
Where a state needs something changed on the host — an address allowed in a firewall, the wpocto/v1 namespace excluded from a JWT plugin, a path excluded from a cache — the Health page writes the instruction with what it found, and the table above says the same thing so it can be acted on without the page in front of you.
A temporary cause — timeout, refused, an HTTP error, unknown — is asked again after 5, 15, 30, 60, 120 and then every 360 minutes; a structural one — firewall, credential, plugin, certificate, DNS — after 1, 3, 6, 12 and then every 24 hours. Always asked again: the thing that fixes a structural cause happens on the site without telling the platform. Every call the site makes to the platform also brings the next check forward.
The site is reachable but its data is old
The Health page shows each dataset with its age and the channel it last came over. Data that ages while the site is reachable means the platform's read of that dataset failed; the failure is recorded and the age shown rather than a fresher time invented. Data that ages while the site is not reachable means the site's own calls have stopped: its WP-Cron is not running, or its outbound HTTPS is blocked. Load a page on the site, or check whether the host disabled WP-Cron.
Another operation is running
The site refuses a second operation while a backup, a restore or a worker update runs, and says so. The platform waits and asks again; nothing is needed from you. A lock left by a crashed process expires after fifteen minutes.
A backup stops at a step
The worker records each step; the platform continues it on the next call and decides failure only from the site's own reported progress — no change for a set time, or an operation older than its ceiling. A backup that is slow is not a backup that failed. If a site's backups never complete, the usual cause is a host that kills the process before a single step finishes; the step size adapts, but a host that gives a request a few seconds cannot back up a large site.
The plugin fails on load
If the site is down because of the worker, the platform puts the previous version back through the worker's recovery files, which work without loading any plugin. Uploading the current zip over the broken install is the manual equivalent. Recovery.
Where to look on the site
Octo Tools → Error log shows the errors the site served, with per-request hits; Activity log shows who changed what, with the platform's actions named as such; the worker's own debug log is under wp-content/uploads/wpocto-log/. The platform's actions on the site appear in the dashboard under the site's activity and update rounds.