Troubleshooting

“Pairing Required” or “Unauthorized” on Connect

Fix node connection failures by aligning pairing state, active token, and public URL settings in one clean pass.

⏱ About 4 minutes
What this means

Your app is reaching a gateway, but the gateway is rejecting trust state (unpaired node, expired/invalid token, stale browser auth state, or wrong public endpoint).

Using heyron.ai in a browser?

A sudden "Auth failed: pairing required" after an in-browser session freeze is often session-state drift, not a full outage. Treat browser state (cookies/site data) as part of the pairing path.

Fast Recovery Flow

1

Confirm you are connecting to the intended gateway URL

Make sure your app’s connect target matches the gateway you actually restarted/edited. Mixed local vs VPS URLs are the #1 hidden mismatch.

Common trap

You regenerate token on one host, but your app is still pointed at another host.

2

Re-run a fresh pairing flow end-to-end

Generate a new pairing link/code and complete pairing once. Don’t reuse stale screenshots/old QR links.

# Use your current gateway UI/flow to generate a brand-new pairing code. # Then complete pairing immediately from the same app/device session.
3

Verify token + public URL config are from the same environment

If you expose the gateway remotely, confirm your published URL is the one apps can actually reach and that it maps to the same running gateway/token set.

Quick check

Any time you rotate token or change public URL, pair again. Old pairings can become invalid by design.

4

Restart gateway and retry once in a clean app session

After config updates, restart gateway and retry from a fresh app state (close/reopen app, then reconnect once).

openclaw gateway restart
Success check

Connect succeeds without “pairing required” or “unauthorized,” and your node appears online in the expected workspace.


High-Friction Edge Cases

“Bootstrap token invalid or expired”

Generate a new token/code and pair immediately. Some tokens are intentionally short-lived for security.

Local Wi-Fi works, remote access fails

Your local bind may be fine, but remote URL exposure is wrong (DNS, tunnel, or allow-list mismatch). Validate remote URL routing and pair using that same endpoint.

Pairing succeeds, then fails again after restart

You likely rotated token/config unintentionally or restarted a different gateway instance. Reconfirm single source of truth for runtime + config path.

heyron.ai browser session froze, then showed “pairing required”

This is commonly stale browser auth/pairing state. Do one clean browser reset path before deeper debugging:

  • Hard refresh once
  • Sign out, then sign back in
  • Retry in an incognito/private window
  • If still blocked, clear site data for heyron.ai and reconnect with a fresh pairing flow

If multiple users report this at the same time, include that in escalation — it may indicate backend auth instability rather than a single-device issue.


When to Escalate to #help

Post this packet so support can diagnose quickly: