The symptom
A user pressed Start call, waited, and got a screen that said the connection could not be established and that it looked like their network was blocking it. There was a button to report a connection issue. The user was being asked to fix their network.
The truth was simpler: the other person was still on the pre‑call screen and had not pressed Start call either. They never arrived.
Why the statistics said “network”
When a call does not come up, the app collects what the browser knows about the connection: the ICE connection state, the connection state, the gathering state, and every candidate pair the agent knows about. That is the right instinct — without it, the server only learns that a call failed, and a call that failed because no relay candidate was made looks exactly like a call that failed because the network dropped the packets.
But the diagnosis was built from those statistics alone:
const failureReason = (rep) => {
if (!rep) return 'unknown';
if (rep.connection_state === 'failed' || rep.ice_connection_state === 'failed') {
if ((rep.relay_candidates || []).length === 0) return 'no_relay_candidate';
return 'no_route';
}
if (rep.gathering_state && rep.gathering_state !== 'complete') return 'gathering_incomplete';
if (rep.connection_state === 'disconnected' || rep.ice_connection_state === 'disconnected') return 'dropped';
return 'unknown';
};
Here is the problem with that code. A peer connection that was never offered — because the other side never joined the room — makes no candidates at all. The ICE agent stays in the state new. And an ICE agent in the state new, with no candidates, looks exactly like a connection whose details never made it through a broken network.
The statistics were not lying. They were answering a question nobody asked them. The question was never “what did the network do?” — it was “did the other person ever come into the room?”
The fix: ask the first question first
const failureReason = (rep) => {
// The other person never came into the room.
//
// This has to be checked FIRST. A peer connection that is never
// offered makes no candidates at all, so the ICE agent stays in the
// state "new" and every statistic looks like a network that blocked
// the connection details.
//
// Nothing about the network can be concluded from a call in which the
// other person never arrived, so this is its own reason.
if (!peerSeenRef.current) return 'peer_not_joined';
if (!rep) return 'unknown';
...
};
One check, placed above the rest, and the message becomes true: your partner never came. The user is not sent to debug a router; they are told to wait, or to try again later, or to look for a partner who has actually pressed the button.
The rest of the fix is on the server
A correct reason on the screen is worth little if the data behind it is a mess. Three things had to agree:
- One list of reasons. The browser and the server used to have their own ideas of what a failure was called. They now share one list, in one file, and the reason a browser sends is validated against it before it is written. A reason already on the session is kept rather than overwritten.
- One bucket per session in the statistics. The dashboard used to count a session in more than one bar, because the categories were read from different columns with different meanings. Every session now lands in exactly one bucket, and the buckets are built from the same list the app writes.
- Partner absence is not a network problem for the learner. The advice engine turned failure reasons into “try a more stable Wi‑Fi”. A partner who never pressed the button says nothing about the learner's Wi‑Fi, so it is excluded from the pattern that produces that advice.
There is one more small thing with a large effect: the button to report the partner is not shown at all when the partner never arrived. Asking someone to report a person who was not there is both useless and unfair to them.
Before: “it looks like your network blocked the connection — try a more stable Wi‑Fi, check your firewall.” After: “Your partner has not joined yet.” The second one is true, and it is the only one of the two that can be acted on.
How often it happens
In the first measured set of 133 sessions, 8 ended with peer_not_joined and one with a genuine network_disconnect. Before the split, all nine were counted as network failures — and the advice about Wi‑Fi was built on them. The full table is in the measurements.
← All notes · Next: the timer that started before the call did →