Connection troubleshooting

Most connection problems are reachability (ConstellaWP cannot call WordPress) or a token mismatch. Work through the checks in order.

Pairing fails immediately

Symptom	What to check
Invalid URL	Use the public https:// origin (no localhost, no private IPs, no http://)
Plugin not detected	Activate ConstellaWP Agent. Visit https://your-site.example/wp-json/constellawp-agent/v1/status — you should see JSON with "active": true
404 on /wp-json/	Permalinks or a security plugin is blocking the REST API. Temporarily disable REST restrictions and try again
401 / invalid token	Copy the token again from Settings → ConstellaWP. It must start with cwa_ (unless you run a pre-1.1.0 agent)
Timeout	Firewall, Bot Fight Mode, or a WAF may be blocking ConstellaWP. Allow the app’s outbound HTTPS to /wp-json/constellawp-agent/

Caution

If you put the site behind HTTP basic auth or a maintenance plugin that blocks unknown visitors, pairing and heartbeats will fail. Allow REST routes under /wp-json/constellawp-agent/ or disable the block for those paths.

Site shows Offline

Offline means ConstellaWP could not complete a signed request to the agent (connection error, timeout, or DNS). Typical causes:

• The site is down or DNS does not resolve
• SSL certificate expired or hostname mismatch
• Hosting firewall / Cloudflare challenge on REST requests
• WP-Cron not running, so heartbeats stall (the agent schedules a heartbeat every 5 minutes)

Fixes:

1. Load the WordPress front-end and wp-admin yourself.
2. Confirm GET /wp-json/constellawp-agent/v1/status from a machine outside the host network.
3. Trigger WP-Cron (real cron calling wp-cron.php is more reliable than the default pseudo-cron).
4. After the site responds, ConstellaWP marks it active again on the next successful heartbeat or job.

Disconnected or authentication errors

If jobs fail with invalid_signature, expired_timestamp, replayed_nonce, or invalid_token:

1. Open WordPress Settings → ConstellaWP and confirm the plugin still shows connected.
2. If you regenerated the token, paste the new one in ConstellaWP site Settings and reconnect.
3. Check the WordPress and ConstellaWP server clocks. Signatures reject timestamps older than 5 minutes.
4. Rate limiting: 10 failed auth attempts from one IP in 10 minutes return HTTP 429 (rate_limited). Wait and retry.

REST API and security plugins

WordPress security plugins sometimes disable REST for anonymous users. The status endpoint is unauthenticated on purpose (it only reports that the plugin is active). Authenticated endpoints (verify, info, register, jobs) require the HMAC headers.

Allowlist:

• GET /wp-json/constellawp-agent/v1/status
• POST /wp-json/constellawp-agent/v1/verify
• GET /wp-json/constellawp-agent/v1/info
• POST /wp-json/constellawp-agent/v1/register
• POST /wp-json/constellawp-agent/v1/jobs

Still stuck

• Confirm PHP 8.1+ and WordPress 6.0+.
• Disable a caching plugin’s “disable wp-cron” option if heartbeats never fire.
• Check the site Events tab for site.offline and job failure payloads.
• Reinstall the plugin only as a last resort — that generates a new token and requires a reconnect.