Skip to content

Troubleshooting

Jump to bottom
Nick edited this page Mar 8, 2026 · 2 revisions

Troubleshooting

A guide to the most common issues and how to resolve them.

Connection Issues

"Not connected" after completing the device flow

The authorization may have timed out. Device codes expire after a few minutes. Click Connect to Telex again to start a fresh flow.

Device code expired before you could enter it

Code validity is short by design. Start the flow again — the new code will be valid for the full window.

Cannot reach telex.automattic.ai

Your server needs outbound HTTPS access on port 443. Check:

  1. Your hosting provider or firewall isn't blocking outbound requests.
  2. A security plugin (Wordfence, Sucuri, etc.) isn't blocking the Telex domain.
  3. wp_remote_get('https://telex.automattic.ai') returns a success in Site Health.

Install / Update Failures

"Checksum mismatch" error

The downloaded file doesn't match the expected SHA-256 hash. This is usually a transient network issue. Try again — if it fails consistently, open an issue.

"Could not create directory" / filesystem error

WordPress needs write access to wp-content/plugins. Check that:

  • The web server user has write permission on the plugins directory.
  • DISALLOW_FILE_MODS is not set to true in wp-config.php.
  • FS_METHOD is not forcing an FTP connection that isn't configured.

Install succeeds but block doesn't appear in the editor

The block plugin was installed but may not be activated. Go to Plugins and check its status. Dispatch activates blocks automatically on install, but activation can fail silently if another plugin catches the error.

Circuit Breaker

"API is unavailable" / circuit breaker open

Dispatch tripped its circuit breaker after detecting repeated API failures. The breaker resets automatically after 60 seconds. To reset it immediately:

wp telex circuit reset

Or go to Dispatch → Settings and click Reset Circuit Breaker.

Check the Telex status page for any ongoing incidents.

Webhook

Webhook returns 401

The HMAC signature doesn't match. Confirm the secret in Telex exactly matches the one in Dispatch → Settings → Webhook.

Webhook returns 410

The request timestamp is more than 5 minutes old. Check your server's system clock is synchronized (NTP).

Webhook fires but no update happens

Check the Dispatch activity log for an error entry. Common causes:

  • Circuit breaker is open — run wp telex circuit status.
  • Project is pinned — pinned projects ignore webhook triggers.
  • The project ID in the webhook payload doesn't match any installed project.

Performance

Admin page loads slowly

The project list is cached. If the cache is expired, the first load fetches from Telex. Subsequent loads use the cache. To pre-warm the cache:

wp telex cache warm

High memory usage during updates

Large builds consume memory during download and zip extraction. If you hit PHP memory limits, increase memory_limit in php.ini or .htaccess and try again.

Getting More Help

Run the built-in health check for a quick diagnosis:

wp telex health

For connection and API status, check Tools → Site Health → Info → Dispatch for Telex.

If the issue persists, open a GitHub issue and include:

  • The output of wp telex health
  • The Site Health debug info (copy via Tools → Site Health → Info → Copy site info to clipboard)
  • The Dispatch version and your WordPress / PHP versions

Clone this wiki locally