6. If it fails

Quick checks before you dig into wire captures. Most cold-start failures are empty ports, a region still syncing, or a subscribe that is simply too large.

1. Is the region even up?

curl -sS https://relay.bitcraftsync.app/health | jq '
  .sources | to_entries[]
  | {name: .key,
     port: .value.port,
     database: .value.database,
     schema_cached: .value.schema_cached,
     upstream: .value.metrics.upstream.state,
     stdb: .value.metrics.local_stdb.state}
'

2. Cache HTTP vs WebSocket

curl -sS https://relay.bitcraftsync.app/cache-health | jq '{ready, regions: [.regions[] | {region, ready}]}'

If ready is false for a region, /player / /claim may omit that shard. WebSocket to the region frontend can still work while the cache is loading.

3. Subscribe never Applied / connection drops ~90s

1. Shrink the query Full SELECT * FROM … on a multi-hundred-MB table can stall or get edge-reset. Add a WHERE (see SQL notes) or subscribe one table at a time.
2. Raise client max message size SDKs / websockets often default to tens of MiB. Set unlimited / very high for BitCraft dumps.
3. Prefer HTTP for joined views /player/…/skills already did the heavy subscribe on the host — no giant Applied on your laptop.
4. Confirm greeting first If you never saw InitialConnection / IdentityToken, you are not ready to Subscribe (Connect).

4. Common client mistakes