Bug Reporting for Games With Host Migration

Host migration is what stops a match from dying the instant the host rage-quits or loses connection. The game elects a new host, transfers authority for the shared world, and ideally the remaining players barely notice. In practice the handoff is one of the most fragile moments in any peer-hosted game, because it has to reconstruct authoritative state on a peer that only ever held a replicated copy, and it has to do so in the chaos of a connection that just dropped. When it goes wrong, players lose progress, objects duplicate or vanish, or the match freezes. This post covers the state you need to capture across the transfer so a migration bug becomes reproducible rather than a shrug and a restart.

The handoff is the dangerous moment

A host holds the authoritative version of shared world state; every other peer holds a replicated, slightly stale copy. When the host leaves, the new host is promoted from one of those replicas, which means the authoritative state is reconstructed from data that was never authoritative and may be missing the host's most recent unreplicated changes. Anything the old host knew but had not yet sent, a pickup it just processed, a door it just opened, is at risk of being lost in the gap between its last replication and its departure.

This is why migration bugs are fundamentally about the boundary between two authorities. The state was correct before the host left and is correct after the new host stabilizes, but in the transfer something fell through. Reproducing it requires seeing the world as the old host last replicated it and as the new host first reconstructed it, so you can diff the two and find what was dropped or doubled. A report that only shows the after state cannot tell you what the before state was, which is exactly the comparison you need.

Dropped, duplicated, and frozen state

The three classic migration failures are loss, duplication, and stall. Loss happens when the new host's replica was missing recent changes, so progress silently rolls back. Duplication happens when the migration replays or re-spawns entities the new host already had, leaving two of something there should be one. Stall happens when authority is ambiguous during the transfer and no peer takes ownership, so the world freezes until something times out. Each leaves a different fingerprint, and capturing the entity counts and IDs before and after makes the fingerprint visible.

These failures are often timing-dependent: the same migration succeeds when the host leaves cleanly and fails when it drops mid-action, because the in-flight operation was neither fully applied nor fully discarded. Capturing what the old host was doing in its final ticks, the operations it had started but not confirmed, is what explains a duplication or a loss that only happens under abrupt disconnects. Without that final-tick context, the bug looks random, when in fact it is precisely tied to an interrupted operation that your handoff does not handle.

Election and the authority timeline

Before state can transfer, the peers must agree on who the new host is, and the election itself is a source of bugs. If two peers conclude they are the new host, you get a split-brain where both apply authoritative changes and the world diverges. If the election is slow, the gap with no authority lengthens and the chance of a stall grows. Reports should capture the election outcome, how long it took, and whether any peer briefly believed it was host, because a contested election is a different bug from a clean election with a bad handoff.

The authority timeline ties the whole thing together: a record of which peer held authority for the shared world at each moment across the transfer, ideally with tick numbers. This timeline shows whether there was a clean baton pass, an overlap where two peers were authoritative at once, or a gap where none were. Most migration bugs are a defect in this timeline, and once you can see it laid out, the fix usually becomes obvious. Capturing it requires every peer to log its own belief about authority, since no single peer has the full picture during a migration.

Connection chaos during the transfer

Migrations rarely happen in calm conditions; they happen because a connection failed, which means the network is already degraded when the handoff begins. Other peers may be experiencing the same packet loss that took down the host, so the migration messages themselves can be delayed or dropped. Capturing the connection state of the surviving peers at the moment of migration, their round-trip times and recent loss, tells you whether a failed handoff was a logic bug or simply a transfer that could not complete on a network that was falling apart.

This context also helps you set expectations for what your migration can survive. A handoff that works when one peer leaves cleanly but fails when the host and another peer drop simultaneously is hitting a real limit, and the report's connection state names that scenario. Distinguishing migrations that failed due to a code defect from those that failed due to genuinely impossible network conditions keeps you from chasing bugs that are really requests for graceful degradation, like saving progress so a doomed match can at least resume later.

Setting it up with Bugnet

Bugnet's in-game report button captures state on each device, which is exactly what a migration bug needs, because the truth is split across the old and new host. Configure peers to capture a snapshot when a migration is detected: the world state the old host last replicated, the state the new host reconstructed, the entity counts and IDs on each, the election result and duration, and the authority timeline. Add player attributes for whether the peer was the departing host, the new host, or a bystander. Several reports around one migration then let you diff before against after.

Migration bugs recur with the same shape, so Bugnet's occurrence grouping folds duplicates into one issue with a count, showing that a specific item type duplicates on migration repeatedly rather than as scattered one-offs. Use custom fields for failure type, election duration, and entity-count delta, then filter to find whether losses cluster around abrupt disconnects. One dashboard assembles the multi-peer evidence and the recurrence count that tell you which part of your handoff, election, state transfer, or in-flight operations, is actually broken.

Testing the worst case on purpose

You cannot wait for real hosts to leave to test migration; you have to force it, and force it ugly. Kill the host process mid-action, drop the host's connection abruptly while it is processing a pickup, make two peers race to claim hostship, and degrade the surviving peers' connections during the transfer. The clean case almost always works; it is the interrupted, contested, lossy migrations that ship broken. Capturing before-and-after state during these forced tests reveals exactly which operations your handoff fails to preserve.

Make migration correctness a tracked property: replay forced-migration scenarios on every build and assert that entity counts and progress survive the transfer. Treat a regression as a blocker, because lost progress is one of the most trust-destroying bugs a multiplayer game can have. Over time, the captured before-and-after snapshots become a regression suite that catches the day someone changes replication and quietly breaks the handoff. Migration is hard, but it is testable, and the teams that test the worst case ship matches that survive their hosts leaving.

Migration bugs live in the handoff. Capture the world before and after the transfer plus the authority timeline, and dropped progress becomes a diffable change.