How do you report desync bugs in multiplayer games?

Desync bugs require reports from multiple perspectives. Describe what each player sees at the moment of desync. Include timestamps and session IDs so developers can correlate server logs.

Why are multiplayer bugs harder to reproduce?

Multiplayer bugs often depend on timing, network conditions, and the actions of multiple players simultaneously. Network latency, packet loss, and jitter add non-determinism that makes exact reproduction difficult.

Bug Reporting Best Practices for Multiplayer Games

Quick answer: Beyond standard fields, multiplayer bug reports should include: the reporter's role (host or client), player count, approximate ping, server region, whether the bug was visible to all players or only the reporter, and the network type.

This guide covers bug reporting for multiplayer games in detail. Multiplayer bugs are the hardest bugs to report well and the hardest bugs to fix. A single-player bug is a conversation between the game and one player. A multiplayer bug is a conversation between the game, a server, network infrastructure, and two or more players who may each see something different. Standard bug report templates are not enough. Multiplayer bugs require additional context — network conditions, player roles, session state, and multi-perspective descriptions — that single-player reports never need.

The Multiplayer Bug Report Template

Your standard bug report template needs multiplayer-specific fields to capture the information developers need to investigate network-dependent issues.

## Multiplayer Bug Report Template

Title:           [What] - [Where/When]
Severity:        [P0-P3]
Game Version:    [Build number]

# Multiplayer Context
Role:            [Host / Client / Dedicated Server]
Player Count:    [Number of players in session]
Server Region:   [e.g., US-East, EU-West]
Connection:      [Wired / WiFi / Cellular]
Approx Ping:     [e.g., ~45ms]
Session ID:      [From in-game overlay or logs]

# What Happened
Reporter sees:   [Game state from your perspective]
Other players:   [What other players reported seeing]
All affected?:   [Yes - all players / No - only reporter]

# Reproduction Steps
  1. [Starting state including player count and roles]
  2. [Actions taken by each relevant player]
  3. [Trigger condition]

Frequency:       [Always / Often / Rare]
Screenshot/Video: [Attached]

Reporting Desync Issues

Desynchronization bugs are the signature challenge of multiplayer game development. Two players in the same session see different game states: one player sees the enemy at position A while another sees it at position B. The game is functioning on each client individually, but the shared reality has diverged.

Reporting desync requires describing the game state from multiple perspectives. A single-perspective report — “the enemy teleported” — is almost useless because the developer cannot tell whether the enemy actually teleported for everyone, or whether the reporter’s client desynced from the authoritative state.

When possible, coordinate with other players in the session to get their descriptions before filing the report. A desync bug with two matching accounts from different perspectives is exponentially more useful than a single-perspective report. Include the session ID so the developer can pull server logs.

Note whether the desync is visual (cosmetic disagreement), mechanical (different gameplay outcomes), or progressive (worsens over time until unplayable). Each type has different implications for the root cause.

Host vs Client Bugs

In peer-to-peer and listen server architectures, many bugs only manifest for clients, not for the host. The host has the authoritative game state and never experiences the latency-induced inconsistencies that clients deal with. A bug report that does not specify whether the reporter was the host or a client is missing critical debugging information.

Always include your role in the session. If the bug only happens to clients, say so. A bug that “only happens when I am not the host” immediately tells the developer to look at client-side prediction, reconciliation, or state replication code.

For bugs that involve interactions between two players, note the roles of both. “Host player picks up item, but client player sees the item still on the ground” is a replication bug. “Both players pick up the same item simultaneously, and both receive it” is a race condition. The relationship between roles and the bug’s manifestation is diagnostic.

Network Condition Reporting

Many multiplayer bugs are latency-dependent. They only occur above a certain ping threshold, or only when there is packet loss. A bug report that says “the hit did not register” without ping information is incomplete. A report that says “the hit did not register, my ping was approximately 150ms, and this happens consistently above 100ms but never below 50ms” gives the developer a clear starting point.

If your game has a network statistics overlay, include a screenshot of it with your bug report. The overlay typically shows current ping, packet loss percentage, jitter, and bandwidth usage. For bugs that seem related to network quality, try to reproduce them under different conditions — wired instead of WiFi, different server regions — and report the results.

“Half our multiplayer bug reports used to say ‘it was laggy.’ Once we added a network info overlay and required a screenshot of it in every multiplayer report, we could actually distinguish between network bugs and logic bugs. Our fix rate doubled.”

Related Issues

For a comprehensive guide on multiplayer bug reporting, see how to report bugs in multiplayer games. For debugging desync issues, read how to debug multiplayer desync issues in games. For an overview of debugging tools, check out network debugging tools for online games.

Add a network stats overlay to your development builds today. Every multiplayer bug report should include a screenshot of the overlay at the time of the bug.