B · Launching Effectstream + Local Dev · APPENDIX
Troubleshooting
Symptom → cause → fix. First move is always the same: bunx orchestrator status.
▼ details below
| Symptom | Cause | Fix |
|---|---|---|
| Everything runs, no errors, but nothing ever appears in the API | NTP (UDP 123) blocked — the main timeline can't sync time, so no blocks are processed. Common on corporate VPNs/hotel Wi-Fi. | Test with sntp time.google.com (mac) / ntpdate -q pool.ntp.org (linux). Switch networks or disable the VPN. |
| Mints sync but everything stalls after some point; or nothing syncs and a Midnight process is red | A Midnight process (node/indexer/proof server) died — parallel chains gate the whole pipeline. | bunx orchestrator status, then bunx orchestrator logs midnight-node (or indexer). Usually fixed by stop + start again. |
Foundry's forge was not found / compact was not found |
Startup hard-checks both toolchains. | Install per Setup; restart your shell so PATH updates. |
| Frontend build dies with heap out of memory / SIGKILL | vite needs ~3 GB heap (the bundle includes the Midnight wallet SDK). | Free RAM; if using Docker/VM give it ≥ 6 GB. |
address already in use on 8545/9944/10599… |
A previous run is still holding ports. | bunx orchestrator stop. Still stuck: lsof -ti tcp:8545 | xargs kill. |
| First launch hangs downloading | Midnight binaries come from GitHub releases on first run. | Wait it out on good Wi-Fi; it's a one-time download. |
| MetaMask: tx stuck pending / nonce error after a restart | The chain was reset but MetaMask remembers old nonces. | MetaMask → Settings → Advanced → Clear activity tab data (per account). |
| MetaMask mint rejected / wrong chain | Not on the local Hardhat network. | Use the game's Connect wallet button — it adds/switches to chain 31337. |
Placements accepted by batcher (success:true) but never reach the map |
Either the Game_L2 primitive isn't in config.dev.ts yet (Step 4), or the batcher/node namespaces don't match. |
Finish Step 4; check namespace in batcher.dev.ts equals "evm-midnight-node", then restart batcher + sync. |
bun run build:pgtypes fails with Failed to listen |
pgtyped starts its own PGLite on port 5432 — it conflicts with the running stack's database. | Run it while the stack is stopped (bunx orchestrator stop), then start again. |
| Cards/map render but battle math seems off | You tuned constants in game.ts and only restarted one piece. |
bunx orchestrator restart sync — the STM lives in the sync process. |
Nuke it from orbit
bunx orchestrator stop
bun run dev