HiveCast Product

Appearance

Device pairing failed ​

Pairing fails in one of three ways:

  1. The CLI errors immediately — wrong cloud URL, bad flag, missing prerequisite.
  2. The CLI runs and seems to succeed, but the Device doesn't show up in the cloud's Devices list.
  3. The CLI hangs forever waiting for browser approval.

Triage ​

Failure 1: CLI errors immediately ​

Common error messages:

ErrorCauseFix
MX CLI not found in HiveCast packageWrapper bundle is incompleteRe-build: pnpm --filter hivecast build
getaddrinfo ENOTFOUND hivecast.aiDNS / connectivityCheck network; can you curl https://hivecast.ai/healthz?
certificate has expiredTLS issue with the cloud endpointCloud-side problem; report it. For self-hosted: renew TLS cert
Invalid setup codeThe setup code is expired or wrongGenerate a fresh one from the cloud Devices page

Failure 2: CLI succeeds but Device doesn't appear ​

Verify locally first:

bash
hivecast whoami --home <host-home>
hivecast link-status --home <host-home>

If whoami says "not linked" but you got "success" output from login, something erased the link record. Check:

bash
ls -la <host-home>/credentials/hivecast-link.json

If missing — re-run pairing. If present:

bash
cat <host-home>/credentials/hivecast-link.json | jq .

Look for:

  • hostId — should be set
  • authorityRoot — should match cloud's expected root for your principal
  • cloud.url — should match the cloud you're trying to pair to

If the link is on disk but the cloud Devices list doesn't show it, the heartbeat isn't reaching the cloud. Check host.control runtime stderr:

bash
tail -100 <host-home>/logs/runtimes/RUNTIME-HOST-LOCAL-*-HOST-CONTROL.stderr.log

Common causes:

  • Cloud /_auth/host-link/heartbeat endpoint is rejecting the JWT (cloud-side system-auth issue).
  • Network blocks outbound to hivecast.ai.
  • The Device's NATS leaf connection is failing — runtime errors will say connection refused against the cloud's WSS endpoint.

Failure 3: CLI hangs forever ​

Browser-pair flows wait for user approval. If you've approved but the CLI is still waiting:

bash
# Cancel the CLI (Ctrl-C)
# Then check the link record
ls -la <host-home>/credentials/hivecast-link.json

If the link wrote successfully, the CLI just got stuck in a polling loop without seeing the approval. The link is real; you can Ctrl-C. Verify with hivecast whoami.

If the link didn't write, the cloud-side approval flow didn't complete on its end. Most common cause: you signed into the wrong account in the browser, or you closed the approval tab too early.

For the device-code form (setup-code path):

bash
hivecast login --setup-code <code> --cloud https://hivecast.ai --home <host-home>

…the code expires after ~10 minutes. After that, the cloud rejects the redemption. Generate a fresh code.

Verifying the cloud is reachable ​

bash
curl -fsS https://hivecast.ai/healthz
curl -fsS https://hivecast.ai/.well-known/hivecast/version

Should both return 2xx. If they fail, the cloud is the problem, not your Device.

"Wrong principal / wrong Space" ​

If you successfully paired but to the wrong account or wrong Space:

bash
hivecast logout --revoke-cloud-link --home <host-home>
# Then re-pair to the right one
hivecast login --device --cloud https://hivecast.ai --route-key correct-space-path --home <host-home>

logout --revoke-cloud-link is important — without it, the cloud will keep showing this Device as linked to the previous principal/Space until heartbeat goes stale.

"I want to pair to a self-hosted cloud, not hivecast.ai" ​

The --cloud flag accepts any HiveCast-shaped endpoint. The endpoint must:

  • serve /_auth/host-link/start (begin enrollment)
  • serve /_auth/host-link/redeem (accept device-code redemption)
  • serve /_auth/host-link/heartbeat (accept ongoing heartbeats)
  • have OAuth provider credentials configured if browser-pair is required

If pairing fails against a self-hosted cloud, check the cloud-side system-auth and system-gateway-http runtime logs.

"Pairing succeeded but auth.mode: 'public-session' on the local Host" ​

If the local Host is in public-session mode (target is for cloud-platform Hosts only), pairing semantics are different — the Host plays the cloud role itself. This is unusual; for normal Devices, ensure host.json has auth.mode: 'local-client'.

"I can't tell if pairing went through" ​

Run hivecast doctor --cloud https://hivecast.ai --home <host-home>. The cloud-aware variant runs additional checks: cloud reachability, Google login redirect, OAuth state persistence (per runHostDoctor in hivecast.mjs:1031-1187). If any of these fail, the pairing path can't work.

When all else fails ​

Capture diagnostics and file an issue:

bash
hivecast doctor --json --cloud https://hivecast.ai --home <host-home> > /tmp/doctor.json
tail -200 <host-home>/logs/runtimes/RUNTIME-HOST-LOCAL-*-HOST-CONTROL.stderr.log > /tmp/host-control.log

See Collect diagnostics for a more thorough capture.

See also ​

Source: projects/matrix-3/packages/hivecast/bin/hivecast.mjs lines 1595-1635 (runHiveCastLinkCommand flow), 1031-1187 (runHostDoctor cloud checks); WORKSTREAMS/product-launch/HIVECAST-DEVICE-ENROLLMENT-SPEC.md.