Edge / User Admin

Appearance

Troubleshooting ​

Quick fixes for the most common Edge / Device problems.

Edge says "checking" forever ​

Symptom: The page renders the loading view but never advances.

Likely cause: Probes are hanging (no response, no timeout).

Fix: Open browser dev tools, look at network requests. If /healthz is hanging, the local gateway is wedged.

bash
# Verify directly
curl -fsS http://127.0.0.1:3100/healthz

# If that hangs, restart the Host
hivecast stop && hivecast start --home <host-home>

"local owner" pill is red ("check service") ​

Symptom: /healthz failed.

Fixes (in order of likelihood):

bash
# 1. Is the Host running?
hivecast status --home <host-home>

# 2. Is the gateway on the expected port?
matrix invoke host.control status '{}' --home <host-home>
# Look at gateway port; cross-check with the URL you opened.

# 3. Restart
hivecast stop && hivecast start --home <host-home>

# 4. Check supervisor log
tail -50 <host-home>/logs/host-service.log

App launcher empty ​

Symptom: "/api/apps returned successfully, but the app list was empty."

Cause: No webapp runtimes are registered.

Fixes:

bash
# 1. Confirm runtimes are running
matrix invoke system.runtimes runtimes.list '{}' --home <host-home>

# 2. If runtimes exist but webapp metadata is missing, reseed
hivecast seed --home <host-home>
hivecast start --home <host-home>

# 3. If runtimes are missing entirely, the supervisor lost them — reseed should restore.

App route returns 404 ​

Symptom: Click "Open Director," browser shows 404.

Causes:

  • The runtime is not running.
  • The runtime is running but didn't register webapp metadata.
  • The route prefix in matrix.json doesn't match the URL.

Fixes:

bash
# Check runtime presence
matrix invoke system.runtimes runtimes.list '{}' --home <host-home>
# Look for the app's runtime.

# Restart it
matrix invoke system.runtimes runtimes.restart '{"mount":"<mount>"}' --home <host-home>

# Inspect package metadata
cat <host-home>/.matrix/packages/<package-name>/matrix.json

Pair flow stuck on "authorization_pending" ​

Symptom: CLI polls forever after hivecast login --device.

Causes:

  • User hasn't approved the user code yet.
  • namespace_required — the principal lacks a Space matching the requested routeKey.

Fixes:

bash
# Check device-link status
matrix invoke system.auth auth.device.status '{"userCode":"<code>"}'

# If status === 'namespace_required':
matrix invoke system.auth auth.namespace.list '{"principalId":"<your-id>"}'
# If empty, claim a path:
matrix invoke system.auth auth.namespace.claim \
  '{"principalId":"<your-id>","routeKey":"<spacePath>"}'

# Then re-approve from the browser.

Symptom: Pair flow finished, but Edge still says optional / not linked.

Causes:

  • <host-home>/credentials/hivecast-link.json did not get written.
  • The Host needs a restart to pick up new bootstrap data.
  • A stale browser tab is showing old data.

Fixes:

bash
ls <host-home>/credentials/hivecast-link.json
# If missing, the exchange step failed. Re-run pair.

hivecast stop && hivecast start --home <host-home>

# Hard reload Edge.

Heartbeats failing ​

Symptom: https://hivecast.ai/apps/web/#dashboard shows this Device offline.

Fixes:

bash
# 1. Local Host running?
hivecast status --home <host-home>

# 2. host.control running?
matrix invoke host.control status '{}' --home <host-home>

# 3. Tail heartbeat log
tail -50 <host-home>/logs/runtimes/host-control.log

# 4. Force credential refresh
mx refresh-credentials --home <host-home>

# 5. Check network reachability
curl -i https://hivecast.ai/_auth/host-link/heartbeat
# (will return 401 without a token — that's fine, just confirms reachability)

"/api/auth/me" returns anonymous in linked mode ​

Symptom: Edge thinks you're not authenticated even though you're paired.

Likely cause: You're loading Edge from the linked URL (https://hivecast.ai/<spacePath>/edge/) without a HiveCast session cookie.

Fix: Sign in to https://hivecast.ai/apps/web/ first; reload the linked Edge URL. Or use the loopback URL http://127.0.0.1:3100/apps/edge/ which gives local-owner identity.

NATS authentication errors in browser console ​

Symptom: Console errors like "NATS PERMISSIONS_VIOLATION."

Causes:

  • The browser's Bus token expired (5 minute TTL; auto-refreshes every 4 minutes).
  • Authority root mismatch — Bus token was issued for one root, request is for another.

Fixes:

  • Reload the page (forces fresh Bus token).
  • Check /api/bootstrap returns the expected authorityRoot.
  • If persistent, see P1.22b in WORKSTREAMS for the fix path.

Device shows wrong hostName ​

Symptom: Renamed the Device but Edge still shows the old name.

Cause: Rename today requires re-pair (see Rename).

Fix: Re-pair with --device-name "<new>".

Apps work locally but cloud URL fails ​

Symptom: http://127.0.0.1:3100/apps/director/ works; https://hivecast.ai/<spacePath>/director/ does not.

Causes:

  • Cloud routing for the Space path is misconfigured (Caddy, DNS).
  • The Device is offline (heartbeats failing).
  • The Director runtime is not registered as webapp in system.devices.

Fixes:

  • Check Device status in https://hivecast.ai/apps/web/#dashboard.
  • Verify route plan in Edge for Director — if assetMount is missing, the runtime didn't register fully.
  • Restart the Director runtime: matrix invoke system.runtimes runtimes.restart '{"mount":"director"}'.

See also ​

Source: Operational experience captured in WORKSTREAMS/loose-ends/items/P1.22* progress logs.