Troubleshooting Plugin Connection

If the dashboard shows your site as offline, pushes fail, or content doesn’t update, work through this list top-to-bottom. We’ve ordered it by likelihood.

Quick decision tree

Site shows "Offline" in dashboard
├── Plugin not installed/activated → install + activate
├── Plugin installed, dashboard shows "Not connected" → re-paste connection code
├── Plugin installed + connected, but no heartbeat
│   ├── Heartbeat cron not scheduled → see Section 1
│   ├── Heartbeat blocked by filter → see Section 2
│   ├── Outbound network blocked → see Section 3
│   └── api_secret out of sync → see Section 4
└── Plugin connected + heartbeats but pushes fail
    ├── REST endpoint unreachable → see Section 5
    ├── Page/CDN cache → see Section 6
    └── Token-version mismatch → see Section 7

Section 1 — Heartbeat cron not scheduled

Run on the WP server:

wp cron event list | grep hubbee

Expected: a hubbee_heartbeat event scheduled every ~300 seconds.

If missing:

1. Re-activate the plugin (Plugins → Hubbee → Deactivate → Activate)
2. Or force-schedule:

   wp eval "(new \\Hubbee\\Health\\HeartbeatScheduler())->init();"
   

3. Check wp cron event list again.

WP-Cron disabled? If define('DISABLE_WP_CRON', true) is set in wp-config.php, you must trigger cron via system cron:

*/5 * * * * curl -s https://yoursite.com/wp-cron.php >/dev/null 2>&1

Section 2 — Heartbeat blocked by filter

Check whether a filter is disabling heartbeat:

wp eval "echo apply_filters('hubbee_heartbeat_enabled', true) ? 'enabled' : 'disabled';"

If “disabled”: look in mu-plugins/, functions.php, or any custom plugin for:

add_filter( 'hubbee_heartbeat_enabled', '__return_false' );

Remove or set to __return_true. Same for hubbee_health_report_enabled.

Section 3 — Outbound network blocked

The plugin needs to reach Hubbee Cloud:

curl -I https://api.hubbee.io/heartbeat
curl -I https://api-db.hubbee.io/functions/v1/heartbeat

Both should return 200 or 401 (200 = ok, 401 = unauthenticated, both confirm reachability).

If hangs/timeouts:

• Server firewall blocking outbound 443? (rare, but managed-WP hosts sometimes do this)
• DNS resolver issues? Try dig api.hubbee.io
• Outgoing proxy configured wrong?

For managed WP hosts (WP Engine, Kinsta, etc.) — open a support ticket asking them to allow outbound HTTPS to api.hubbee.io and api-db.hubbee.io.

Section 4 — api_secret out of sync

If the WP database was restored from backup but the dashboard still has the new secret (or vice versa), HMAC verification will fail with bz_invalid_signature.

Symptoms: every push returns 401 from this site, but heartbeat may still work (uses different auth flow).

Fix:

1. Hubbee dashboard → site → Settings → Disconnect
2. Generate a new connection code
3. WP Admin → Hubbee → Settings → paste new code → Connect

A fresh api_secret is exchanged. No data is lost — token definitions and historic pushes are preserved.

Section 5 — REST endpoint unreachable

Test the plugin’s REST namespace from outside:

curl https://yoursite.com/wp-json/bz/v1/status

Expected: JSON like {"site_id":"…","plugin_version":"2.0.2","mode":"agent",…}.

If 404:

• WordPress REST API is disabled (some security plugins do this)
• .htaccess lacks the standard WP rewrite rules
• Permalinks set to “Plain” — set to “Post name” or any pretty permalink and re-save

If 500:

• Plugin fatal error during init. Check wp-content/debug.log
• Conflicting plugin (security plugin renaming wp-json is common)

If 401 on /status: that’s normal — /status is public, but the endpoint may have been renamed by a security plugin like Wordfence. Whitelist wp-json/bz/v1/* in the security plugin.

Section 6 — Page / CDN cache hiding the update

After a successful push, the local DB has the new token, but visitors still see the old value. Almost always caching:

Cache layer	How to purge
WP Rocket	WP Admin → WP Rocket → Clear Cache
LiteSpeed	LiteSpeed Cache → Toolbox → Empty all caches
Cloudflare	Cloudflare dashboard → Caching → Purge Everything (or single URL)
Varnish (managed hosts)	Host’s dashboard, or wp varnish purge
Elementor	Elementor → Tools → Regenerate CSS & Data
Browser	Hard reload (Cmd+Shift+R) or incognito

Pro tip: in mu-plugins/, hook hubbee_after_push to auto-purge:

add_action( 'hubbee_after_push', function() {
    do_action( 'rocket_clean_domain' );
    // or your cache plugin's flush hook
} );

Section 7 — Token-version mismatch

Plugin only accepts higher versions. If you copied a token from a backup with a higher version-number, subsequent pushes look stale.

Diagnosis:

wp db query "SELECT token_key, version FROM wp_bz_tokens WHERE token_key='<your_key>';"

Compare with the version shown in the dashboard. If the WP version > dashboard version, the dashboard pushes will be skipped.

Fix:

• Push a fresh value with the dashboard’s bump-version button (it will bump to local + 1)
• Or: directly clear and let the next push install fresh:

  wp db query "DELETE FROM wp_bz_tokens WHERE token_key='<your_key>';"
  

  (This is destructive. Only do it knowing the dashboard will re-push.)

Section 8 — Component / asset chunks not loading

If you’ve assigned visual effects (backgrounds, elements, text effects) and they don’t render:

// In browser console on the affected page:
window.HUBBEE_DEBUG = true;
HubbeeLive?.hydrate?.();
console.table(Array.from(document.querySelectorAll('[data-bz-component]')).map(el => ({
  slug: el.dataset.bzComponent,
  hydrated: el.dataset.bzHydrated,
  version: el.dataset.bzVersion
})));

The output should show each mountpoint and its hydration state. Common issues:

• hydrated="false" → JS bundle not loaded; check Network tab for 404 on /wp-content/uploads/hubbee/chunks/...
• hydrated="error" → look at console.error() for the actual stack
• Missing data-bz-config → re-push the asset from the dashboard

Resetting cleanly

When all else fails — reconnect from scratch:

1. Dashboard → site → Disconnect
2. WP Admin → Plugins → Deactivate Hubbee
3. (Optional, but clean) WP Admin → Plugins → Delete Hubbee — this triggers uninstall.php which clears all bz_* data
4. Re-install plugin
5. Re-generate connection code in dashboard
6. Re-connect

You’ll lose local token state — the next dashboard push will rebuild it from the SaaS source-of-truth.

Still stuck?

info@hubbee.io with:

• WP version, PHP version
• Active caching plugins, CDN
• Output of wp option list --search="bz_*" --format=json
• Output of wp cron event list | grep hubbee
• Output of curl -I https://yoursite.com/wp-json/bz/v1/status

We typically respond within one business day.