Troubleshooting

A symptom-indexed reference. For each symptom, jump to the first applicable cause and follow the linked diagnostic page.

Browser-side symptoms

"ERR_CONNECTION_REFUSED" hitting the gateway URL

Cause	Fix
Gateway process is not running	hivecast status; hivecast start
Wrong port	Check host.json.http.port; verify with curl 127.0.0.1:<port>/healthz
Bound to 0.0.0.0 vs 127.0.0.1 mismatch	Check host.json.http.host

"404 Not Found" for /apps/<appName>/

Cause	Fix
No runtime registered the app	matrix invoke system.gateway.http gateway.http.status '{}' and verify the app is listed
Runtime is registered but not running	hivecast runtimes; status must be running
Wrong appName (typo, casing)	App names are case-sensitive lowercase kebab-case
Path matches a public-namespace pattern that doesn't resolve	Reserved route key conflict — see Routes / Space routes

→ See Operations / Route diagnostics.

"502 Bad Gateway" with "exceeded relay limit"

The asset is >10 MB. Reduce the asset size or split it. The 10 MB limit is in MAX_RELAY_BODY_BYTES (projects/matrix-3/packages/system-gateway-http/src/index.ts:12).

"WebSocket connection failed" at /nats-ws

Cause	Fix
NATS process down	hivecast status; verify NATS sibling running
Wrong NATS WS port	Check host.json.transport.nats.wsPort; default is 4271 for embedded, 4223 for cloud production
Caddy proxy misconfigured	Check Caddyfile.bare; ensure /nats-ws proxies to NATS port
Browser CSP blocks the WebSocket origin	Verify same-origin; the bootstrap URL must match the page origin

"401" / "403" on app pages

The gateway itself doesn't authenticate today. If you're seeing 401/403, it's coming from system-auth middleware in front of specific endpoints, or from the bus authentication failing. Check the runtime's logs for auth-related errors.

App loads but doesn't connect to NATS

Cause	Fix
/api/bootstrap returns wrong natsWsUrl	Check transport.nats.wsUrl in host.json
Browser-side NATS auth fails	Inspect browser console; look for NATS CONNECT errors
busToken in bootstrap is invalid	Check auth.sessionSecret and auth.mode

→ See Overview / NATS WebSocket.

Operator-side symptoms

hivecast status reports "stopped" but port is bound

A previous gateway process didn't clean up its PID file or state. Force stop:

sudo systemctl stop hivecast-host.service
sudo lsof -i :3100  # find any straggler processes
sudo kill <pid>

Then hivecast start.

/healthz works but /apps/... 404s for everything

The gateway is up, but system.runtimes may not be reachable, so _loadRoutes returns empty. Check:

matrix invoke system.runtimes runtimes.registered '{}'

If this errors, the system runtime is down or the bus has not finished bootstrapping. hivecast doctor may report the issue.

Gateway logs show "Gateway actor has no Matrix context"

The actor was called before bootstrap completed. This is usually transient during startup; if persistent, the actor's parent runtime failed to initialize its bus context. Check the runtime's logs for earlier errors.

Public-route URLs return the platform shell instead of the app

Path matched the public-namespace parser before reaching the generic /apps/ rule. Check that the first URL segment isn't accidentally being parsed as space.<...> / domain.<...> / system.<...>. See Routes / Space routes.

Hot-reload (Vite dev) doesn't update

Origin-backed routes win over asset-mount when both exist. If hot-reload isn't kicking in, verify the runtime's webapp record has origin set, not just assetMount. Check the runtime's runtime.json:

cat <host-home>/runtimes/<runtime-id>/runtime.json | jq .metadata.webapp

Build-time symptoms

pnpm --filter @open-matrix/system-gateway-http build fails

Most likely a cross-package import problem. Check that imports in src/*.ts use the package's own modules or declared dependencies, not ../../../ paths.

Type errors in system-gateway-http

The branch may need pnpm install or a clean rebuild. Try:

pnpm --filter @open-matrix/system-gateway-http build --force

See also

• Operations / Route diagnostics
• Operations / Health
• Operations / Logs
• Reference / Gateway actor ops

Source: Issues observed across projects/matrix-3/packages/system-gateway-http/ and the cloud deploy pipeline. Cross-reference each symptom to the implementation file referenced.