Debug a failed connection

Find out why a player couldn't connect, join, match, or sync.

1. Turn on SDK debug logging

MultiplayerService.set_debug_enabled(true)
# [SpawnWeaver][connection] connected
# [SpawnWeaver][auth] authenticated as player_ab12…
# [SpawnWeaver][error] room_not_found: Room 'ZZZZZZ' was not found.

2. Listen for structured errors

MultiplayerService.sdk_error.connect(func(err):
    # { code, message, details, retryable }
    push_warning(err.message))

State-update rejections arrive separately on state_update_rejected.

3. Copy a debug report

Ask a player to send you their report — it captures client-side state the server never saw.

DisplayServer.clipboard_set(MultiplayerService.create_debug_report_string())

Paste it into the dashboard's Debug bundle viewer to inspect their connection state, last 50 messages, errors, and latency.

4. Use the dashboard debugger

• Sessions — open a player to see a full timeline (connected → authenticated → actions → rejections → disconnected) with their IP and SDK/engine version.
• Errors — common failures grouped by code, each with a suggested fix.
• Live activity — current connections, rooms, lobbies, and the matchmaking queue.

Common causes

• Rejected immediately after connecting — wrong/inactive public key.
• Never connects — wrong URL/port, or the backend isn't running.
• "room_not_found" — wrong code, or the room expired while empty.
• "rate_limited" — sending too fast; back off (it's retryable).