A push failed — what now

A “push” is anything Hubbee sends to a WordPress site: token values, background assets, custom components, text effects, plugin install commands. Most pushes succeed in under 2 seconds. When they fail, the dashboard shows a typed error and we automatically retry. This article tells you what each error code means and what (if anything) you should do.

How to find the failure

Site detail → Activity → Push events. Click the failed row to expand. Three fields matter:

• Error code (typed enum like wp_403, hmac_mismatch, plugin_timeout)
• HTTP status (raw response code from WordPress)
• Retries (how many attempts so far)

Common error codes

wp_403 — WordPress returned forbidden. Most often a security plugin blocking the request. See Firewall and security plugin conflicts. Hubbee retries 3× with exponential backoff (5s, 30s, 120s), then surfaces the failure. Manual retry from the push event detail page once you’ve fixed the firewall rule.

wp_401 — Authentication failed. The site’s api_secret doesn’t match what Hubbee has stored. Causes:

• WordPress was restored from a backup that overwrote the Hubbee credentials
• The plugin was reinstalled and lost state
• The site was migrated to a new hosting environment

Fix: Site → Settings → Connection → Reconnect. Generate a new connection token and re-enroll. Already-pushed content stays on the WordPress side; only the pipe between Hubbee and the site is rebuilt.

hmac_mismatch — Signature verification failed at WordPress. Either the request timestamp is more than 5 minutes off (server clock drift on the WordPress side) or there’s a man-in-the-middle proxy munging the request body. Check the host’s NTP sync first (timedatectl status on Linux); if the clock is off by more than 60 seconds, fix the NTP config. If the clock is fine, look for a reverse proxy or CDN that’s modifying request bodies in flight.

plugin_timeout — WordPress took more than 15 seconds to respond. Usually a slow host, a busy database, or a plugin doing heavy work on every request (Yoast SEO premium with large site, Better Search Replace running, etc.). The push retries 3×. If all three time out, the site is too slow to receive pushes — upgrade hosting, or schedule pushes outside peak hours via Site → Schedule pushes.

network_error — Couldn’t reach the site at all. DNS resolution failed, TLS handshake failed, or the site is fully offline. Check the site is reachable in a browser, then click Retry push.

plugin_too_old — Site’s plugin version is below the minimum. Update the plugin: WP-Admin → Plugins → Hubbee → Update Now. The push retries automatically every 5 minutes for the first hour, then drops to once per hour for 24 hours, then stops. Updating the plugin restarts the retry cycle.

asset_chunk_404 — The pushed asset bundle isn’t available. A background, element, or text effect was assigned but its compiled chunk isn’t on Supabase Storage. Rare — usually a transient deploy issue on our side. Retry in 5 minutes; if it still fails, email support with the asset slug.

token_too_large — Token value exceeds 1 MB. WordPress and Hubbee both refuse to store token values over 1 MB. Trim the content or split into multiple tokens. Note: HTML blocks rarely hit this; raw JSON dumps and Markdown with embedded base64 images frequently do.

rate_limited — The site hit the per-site push rate limit (1000/hour). Almost always the result of a runaway loop somewhere else in the dashboard. Wait an hour; the limit window slides. If you genuinely need >1000 pushes/hour to one site, email support — we can raise the per-site limit for legitimate bulk operations.

Retry policy reference

Error class	Initial retry	Max retries	Backoff
Network (timeout, unreachable)	30s	3	exponential
WordPress 5xx	60s	5	exponential
WordPress 4xx (auth)	none	0	manual only
Plugin too old	5 min	12	linear
Internal (asset 404, etc.)	5 min	3	linear

After max retries, the push moves to status failed and stays in the event log indefinitely for audit. Failed pushes don’t auto-resume when the underlying issue is fixed — you must click Retry manually.

What happens to the WordPress side when a push fails

Failed pushes leave WordPress unchanged. We’re either rejected before WordPress applies anything, or we time out before WordPress finishes — either way the previous content stays in place. The dashboard activity log is the source of truth for what’s currently live on the site.

Atomic rollback

For pushes that did apply but you want to revert: site detail → Activity → Push events → find the most recent successful push you want to keep → three-dot menu → Revert to this version. The plugin restores the snapshot of token values at that point in time.

Rollback only works for token pushes, not for asset assignments or component installs (those don’t keep a versioned history).

Bulk-replay failed pushes

If many pushes failed during an outage and you want to retry them all at once:

1. Activity → Push events → Filter: status = failed, started > [outage window]
2. Select all → Bulk action → Retry

Hubbee dispatches them with a 200ms stagger between each call so we don’t slam the WordPress site.

When to email support

• Same site, same push, fails 3× after you’ve followed this article
• Push status sits at running for more than 10 minutes (different from sync stuck — see Sync stuck)
• Error code not listed above and not obvious from the response body in the event detail panel