Advanced network troubleshooting

Use these notes when Avalanche runs inside a locked-down network. They cover allow-lists, WebSocket fallbacks, and configuration overrides baked into the codebase.

Allow-list required domains

`firestore.googleapis.com` – real-time reads and writes for games, players, and lobby state.
`www.googleapis.com` – Firebase auth token refresh.
`us-central1-avalanche-trivia-8cb6a.cloudfunctions.net` – Cloud Functions API, including the Socket.IO endpoint.
If you deploy your own fork, replace the default Cloud Functions host with your project’s region-specific URL.

Tip: If you see `DNS_PROBE_FINISHED_NXDOMAIN` or `proxy refused connection` errors in devtools, the allow-list is incomplete.

WebSocket considerations

Avalanche upgrades Socket.IO connections to WebSocket. Some corporate proxies permit only HTTP(S) – the handshake then fails.
To confirm, open devtools → Network → WS and watch the status. `101 Switching Protocols` means success; `200` responses that close immediately mean the proxy blocked the upgrade.
If WebSockets are disallowed entirely, set `NEXT_PUBLIC_DISABLE_SOCKETS=true` during build or deployment. The app will rely solely on Firestore and skip socket initialisation.
You can also override the socket URL with `NEXT_PUBLIC_SOCKET_URL` to point at a gateway your network team approves.

Tip: When sockets are disabled you lose instant avalanche prompts, so keep the host event log open to monitor resets manually.

Proxies and SSL inspection

Many schools and offices use SSL inspection appliances. Ensure they trust Google’s certificate chain so Firestore requests do not fail with `net::ERR_CERT_AUTHORITY_INVALID`.
If the proxy rewrites headers, Socket.IO may need the `transport=websocket` option. Set `NEXT_PUBLIC_SOCKET_TRANSPORTS=websocket` to skip long polling attempts that proxies often block.
Check whether your proxy closes idle connections quickly. Socket.IO automatically reconnects, but repeated drops generate `[socket] Connection error` logs and can impact avalanche timing.

Tip: Share packet captures or proxy error logs with your IT team; they show exactly which handshake is being denied.

Local development & staging

Use the `.env.local` file to set the same overrides you expect in production (`NEXT_PUBLIC_SOCKET_URL`, `NEXT_PUBLIC_DISABLE_SOCKETS`, etc.).
When testing offline, run the Firebase Emulator Suite or mock Firestore responses – the production app requires live Google services.
If you need to capture network traffic, start Chrome with `--disable-web-security` in a controlled environment only; never recommend this to end users.

Tip: Keep a README of your networking assumptions so future hosts know which overrides to set in restricted venues.

When things still fail

Every request returns `permission-denied`

This is almost always a Firestore security rules issue or an auth token blocked by the proxy. Confirm the signed-in host has the correct claims and that the proxy is not stripping Authorization headers.

Socket connects, then disconnects every few seconds

Your proxy likely enforces a short idle timeout. Switch to HTTP-only mode (`NEXT_PUBLIC_DISABLE_SOCKETS=true`) or ask IT to extend the timeout for the Cloud Functions host.

Players outside the network cannot join

Ensure the host did not create the game using a local emulator. Only games stored in your production Firebase project are reachable on the public internet.

Back to Troubleshooting Connection