Start Building

Unity Netcode Scene Switch Disconnects Clients - NGO Load Event Fix

Problem: You are using Netcode for GameObjects (NGO). When the host or dedicated server loads a new scene (menu to match, level transition, etc.), clients disconnect, see "Disconnected from host", or never finish loading the new scene. Sometimes the editor host works but a build drops clients, or only some peers fail during LoadScene.

Root cause: Multiplayer scene changes must go through NGO’s scene pipeline, not raw UnityEngine.SceneManagement.SceneManager. If you use the standard LoadScene on server or client without coordination, the NetworkManager can be destroyed with the old scene, scene GUIDs do not match NGO’s tracking, or clients reject the load because they were not moved through the same scene events. Treat scene switching as a server-authoritative operation that NGO orchestrates.

This guide walks through the fixes in order. Bookmark this page for quick reference when you wire up level flow.

Quick fix checklist (do this first)

  1. Only the server should trigger a networked scene load (use IsServer checks).
  2. Call NetworkManager.Singleton.SceneManager.LoadScene(...) (or the equivalent on your NetworkManager instance), not SceneManager.LoadScene for the “main” multiplayer transition.
  3. Persist NetworkManager across loads (DontDestroyOnLoad on its GameObject, or load scenes additively so the bootstrap scene never unloads).
  4. Ensure every scene you load is in File → Build Settings → Scenes In Build, with correct order if you rely on index 0 as bootstrap.
  5. Log SceneEvent callbacks temporarily to confirm Load / LoadComplete fire for all connected clients.

Step 1: Stop destroying NetworkManager when the scene unloads

Symptom: Disconnect happens immediately when loading; host sometimes survives as listen server in-editor because Play Mode keeps objects alive differently than a build.

Why: NetworkManager lives in your bootstrap scene. If that scene is fully unloaded during LoadSceneMode.Single, the manager and transport destroy, so every client loses the connection.

Fix (common pattern):

  1. Put NetworkManager + transport (and optional lobby UI) on a GameObject in a small bootstrap scene (index 0).
  2. In a script that runs once at startup (e.g. on NetworkManager), call DontDestroyOnLoad(gameObject) on the NetworkManager GameObject before you start host/client, or
  3. Use LoadSceneMode.Additive for gameplay scenes so bootstrap never unloads (more setup, but very explicit).

Verification: After loading the gameplay scene, inspect the hierarchy in Play Mode: NetworkManager should still exist. If it is missing, fix persistence before debugging NGO events.

Step 2: Use NetworkSceneManager from the server

Symptom: Clients appear to load the wrong scene, or desync then disconnect; logs may show NGO warnings about scene state.

Why: NGO maintains a scene event state machine per client. Calling SceneManager.LoadScene only on the server (or on clients independently) breaks that contract.

Fix:

  1. Wrap any transition in if (NetworkManager.Singleton.IsServer) { ... }.
  2. Load via NGO, for example:
    • NetworkManager.Singleton.SceneManager.LoadScene(sceneName, LoadSceneMode.Single);
    • Use the scene name string or Build Settings index consistently with how you registered scenes.
  3. Do not call a raw SceneManager.LoadScene for the shared multiplayer world on clients; NGO applies the load to connected clients through its own mechanism.

Verification: With two editor instances (parrel or two players), start host then client, trigger transition from server-only code. Both should land in the new scene without disconnect. If the client drops, continue with the steps below.

Step 3: Confirm build settings and scene registration

Symptom: Disconnect or infinite load on some platforms; works in editor only.

Why: NGO resolves scenes by build index / name. A scene not in the build list cannot load on a player build. Editor may still find assets that builds omit.

Fix:

  1. File → Build Settings
  2. Add Open Scenes or drag every gameplay and menu scene you load through NGO.
  3. Rebuild the client and server targets after changes.
  4. If you use addressables or other late content, this article assumes scenes are standard Scenes In Build; custom flows need matching NGO support.

Verification: Reproduce with a development build and logging on device. No “scene not found” or silent failure after a clean build.

Step 4: Observe SceneEvent callbacks while debugging

Symptom: Intermittent failures; you need to know which client never completes a load.

Why: NGO exposes SceneEvents (load started, completed, etc.). If a client never completes, the transport may time out or the event pipeline stalls.

Fix (temporary diagnostics):

  1. Subscribe to NetworkManager.Singleton.SceneManager.OnSceneEvent (API name may vary slightly by NGO version; use your installed package’s NetworkSceneManager docs).
  2. Log SceneEventType, client id, and scene name for each event.
  3. Fix the first event type where a client diverges (e.g. never receives LoadComplete).

Remove noisy logs before shipping.

Verification: All connected clients show a completed load path for the target scene before gameplay RPCs run.

Step 5: Timing and gameplay hooks after load

Symptom: Clients load the scene but player spawn or RPC fails right after transition.

Why: Your code may run before NGO finishes synchronizing the active scene, or you spawn before OnClientConnected / scene-complete in the new scene.

Fix:

  1. Move spawn and state reset to hooks that run after NGO reports the scene load you care about (e.g. SceneEvent-driven callback or NGO-recommended pattern for your version).
  2. Avoid static singletons that assume the previous scene’s objects still exist.
  3. Ensure NetworkObject player prefabs are registered and spawned only on server as usual.

Alternative approaches

  • Additive loading: Keep bootstrap loaded; additively load arenas and unload them with NGO-compatible flow to reduce risk of destroying core networking objects.
  • Dedicated server builds: Same rules apply: one authority triggers NetworkSceneManager loads; clients follow server-driven events.
  • Scene management packages (e.g. third-party multiplayer lobby tools): Ensure they ultimately call NGO’s scene API for the networked world, not only Unity’s SceneManager.

Prevention tips

  • Document one code path for “we are changing the multiplayer level” and enforce server-only NGO loads in code review.
  • Keep a minimal bootstrap scene that never holds heavy gameplay content so it is easy to mark Don’t Destroy On Load.
  • Add an automated test or logging gate in development builds that asserts NetworkManager.Singleton != null after every scene transition.

Related problems and links

  • Broader NGO errors (RPC, spawn, transport): see Unity Multiplayer Netcode Errors - Networking System Fix.
  • Official Unity documentation: look up Netcode for GameObjects and Scene management / NetworkSceneManager for your package version so enum names and callback signatures match your install.

If this article helped, share it with other developers on your team. For deep networking architecture, pair these fixes with a clear server authority policy for gameplay state.