Bug Reporting for Games With Server Reconnection

A dropped connection is inevitable on mobile and flaky home networks, so a graceful reconnection flow is the difference between a minor blip and a ruined match. The player drops, the server holds their slot for a grace period, and when they come back the server restores their state and resynchronizes them with the ongoing simulation. It sounds simple and it is full of edge cases: the player who reconnects with a stale token, the old session that never got cleaned up so now there are two, the inventory that restores to a moment before a key event. This post covers the handshake timeline, session tokens, and state snapshots you need to capture so a reconnection bug stops being an irreproducible coincidence.

The reconnect handshake and where it breaks

Reconnection is a handshake: the client detects the drop, attempts to re-establish the connection, presents a token proving it owns the existing slot, and the server validates that token, restores the player's state, and brings them up to date with the current simulation tick. Each step can fail in its own way. The drop might be detected late, the token might be expired or rejected, the slot might already have been reclaimed, or the state restore might pull from a stale snapshot. A report needs the timeline of these steps to show where the handshake actually broke.

The hardest reconnection bugs are the ones where the handshake appears to succeed but the result is subtly wrong. The player is back in the match but their position, score, or inventory is from a moment that no longer matches the world. This is a state-restore bug hiding inside a successful reconnect, and it is invisible unless the report captures both the state the server restored and the player's state from just before the drop. Without that comparison you only know the player is upset, not that the restore pulled the wrong snapshot.

Duplicate sessions and ghost players

A nasty and common reconnection bug is the duplicate session. The player's old connection has not been cleaned up, perhaps because the drop was a silent timeout the server has not yet noticed, when the new connection arrives. Now the server has two sessions for one player: a ghost that still occupies a slot, holds a position, and may even be targetable, alongside the real reconnected player. Capturing the active session list for that player at reconnect time makes the duplicate immediately visible, where the player just reports seeing themselves twice or being unable to rejoin.

The root cause is usually a race between the old session's timeout and the new session's authentication. If the new connection authenticates before the old one is reaped, both can coexist. Reports should capture the session tokens and their timestamps for both the old and new connections, so you can see the overlap and measure how long the ghost persisted. This turns a confusing duplicate-character report into a precise statement about a cleanup race, which is a targeted fix in your session lifecycle rather than a vague hunt through the connection code.

State restore and the stale snapshot

When a player reconnects, the server must restore them to a state consistent with the live world, not the state they had when they dropped. If the match advanced during the grace period, restoring the pre-drop state naively rolls the player back: their inventory reverts, their position is wrong, or they lose a kill they earned just before dropping. The correct behavior is to reconcile the held state with everything that happened while they were gone, and bugs here come from skipping or botching that reconciliation.

To debug this you need the snapshot the server held for the player, the events that occurred during the disconnection, and the final restored state. The diff between what the player had, what happened while they were away, and what they got back tells you exactly where reconciliation failed. Sometimes the bug is the opposite: the server applies events that should not survive a disconnect, like damage taken while the player could not act, raising a fairness question. Capturing the during-disconnect events lets you make that policy decision deliberately rather than discovering it through complaints.

Tokens, timing, and the grace period

The grace period, how long the server holds a slot for a dropped player, is a tuning knob that produces bugs at both extremes. Too short, and players who could have reconnected lose their slot and report being kicked unfairly; too long, and slots are occupied by players who are never coming back, degrading the match for everyone. Reports should capture how long the player was disconnected, the grace period in effect, and whether the slot was still held when they returned, so you can tune the period against real reconnect-time data.

Token handling is the security and correctness backbone of reconnection. A reconnect token has to be hard to forge yet survive the exact disruption that caused the drop, which is a genuine tension. Capturing the token's validity window and the reason for any rejection, expired, already used, signature mismatch, distinguishes a security control working as intended from a flow that is too strict for real network conditions. Many a kicked-on-reconnect bug turns out to be a token lifetime shorter than the drops players actually experience, which the captured timing exposes at once.

Setting it up with Bugnet

Bugnet's in-game report button captures state at the moment a player flags a bad reconnect, which is when the handshake artifacts are still in memory and would otherwise be gone after the next clean session. Wire it to serialize the reconnect context: the handshake timeline with timestamps, the session tokens for the old and new connections, the disconnection duration and grace period, the state the server restored, and the player's pre-drop snapshot if the client cached one. Add player attributes for connection type and platform, since reconnection bugs cluster on mobile networks. One report then contains the whole flow.

Reconnection failures recur with the same shape across many players, so Bugnet's occurrence grouping folds duplicates into one issue with a count, showing that duplicate sessions spike on a particular platform rather than logging each as a one-off. Use custom fields for failure type, disconnection duration, and token-rejection reason, then filter to find whether kicked-on-reconnect clusters at disconnection times just over your grace period, the telltale sign your window is too short. One dashboard turns a scattering of I-lost-my-stuff reports into a clear picture of where the flow leaks state.

Testing reconnection deliberately

Reconnection only gets exercised when connections fail, so you must fail them on purpose to test it. Drop a player mid-action and reconnect them after various delays spanning your grace period, reconnect before the old session is reaped to force a duplicate, reconnect with an expired token, and let the match advance significantly during the gap to stress state reconciliation. The happy path where a player blinks out and back instantly almost always works; the bugs live in the long gaps and the races, which only deliberate testing surfaces.

Track your reconnect success rate and the distribution of disconnection durations from field captures, and treat reconnection as a core reliability metric rather than an edge case. A falling success rate or a cluster of failures just past the grace period is actionable tuning data. Keep captured handshake timelines as regression cases and replay them when you touch the session or restore code. Players forgive a dropped connection; they do not forgive coming back to find their progress gone, so a reconnection flow that reliably restores state earns a disproportionate amount of goodwill.

Reconnection bugs hide in the handshake and the restore. Capture the timeline, the tokens, and the before-and-after state, and a bad rejoin becomes diagnosable.