Factorial StudioGameZone

For developers

Unity WebGL Game Stuck on the Loading Screen? 9 Causes and How to Fix Them

By the Factorial Studio team ยท ยท 9 min read

Unity WebGL Game Stuck on the Loading Screen? 9 Causes and How to Fix Them

We host every game on GameZone ourselves, and over the past months we moved twenty-six Unity WebGL builds between three different hosts. Almost every build that "worked locally" broke at least once along the way. The good news is that a WebGL build that hangs on its loading screen is rarely a mystery: it is nearly always one of the nine problems below, and the browser's developer tools will tell you which one within a minute.

Before anything else, open the browser console (F12) and the Network tab, then reload. Sort the Network tab by status and look for anything red. Most of the causes below leave a clear trace there.

1. The server does not say the files are compressed

Unity compresses WebGL builds with Brotli or Gzip by default, producing files such as Build/game.wasm.br and Build/game.data.gz. The browser can only unpack them on the fly if the server sends a Content-Encoding: br or Content-Encoding: gzip header with each one. Many static hosts do not. The console then shows an error along the lines of "Unable to parse Build/game.framework.js.br" and the bar never moves.

  • Fix on the server: serve .br files with Content-Encoding: br and .gz files with Content-Encoding: gzip, plus the right Content-Type for the file inside (application/wasm for .wasm.br, application/javascript for .js.br).
  • Fix in Unity, when you cannot change the server: Player Settings โ†’ Publishing Settings โ†’ turn on Decompression Fallback. Unity then unpacks the files in JavaScript. It loads a little slower, but it works anywhere.
  • Or set Compression Format to Disabled and let the host compress on the fly. The files you upload get two to three times larger.

2. Some of the build was never uploaded

The classic symptom: the loading bar fills, the first scene appears, and then nothing happens. That points at files the build loads after startup, most often the StreamingAssets folder and, for projects that use Addressables, the catalog and asset bundles inside StreamingAssets/aa. They are not referenced in index.html, so any upload process that copies "the files the page uses" misses them.

In the Network tab you will see a 404 for something like catalog.json, catalog.bin or a .bundle file. The fix is to always upload the entire build folder exactly as Unity produced it. We learned this one the hard way: a merge game of ours stopped after level one until 62 MB of Addressables bundles were copied across.

3. StreamingAssets resolves against the wrong address

Unity builds the StreamingAssets URL relative to the page that runs the game. If a portal serves your index.html from its own address (a proxy, or a page with a <base> tag pointing at your files), relative paths for the loader and .data files follow the <base>, but streamingAssetsUrl does not, so it points at a folder that does not exist on the portal.

If you control the template, make it absolute in the config passed to createUnityInstance: streamingAssetsUrl: "https://your-host.example/game/StreamingAssets". If you run the portal, rewrite that one value when you serve the page.

4. The host hides folders that start with an underscore

GitHub Pages runs every site through Jekyll by default, and Jekyll silently drops files and folders whose names start with _. Some Unity packages write asset folders with exactly those names, and they then return 404 on Pages while working everywhere else. Add an empty file called .nojekyll at the root of the repository and Pages serves everything as-is.

5. The files are on another domain and CORS blocks them

When the page and the build live on different domains (a portal page loading files from your CDN, for example), the browser only lets the page read those files if the host sends Access-Control-Allow-Origin. Without it the console reports a CORS error and the loader stops. For public game files, Access-Control-Allow-Origin: * is the usual answer.

6. The game is waiting for focus or a click

Inside an iframe, a game often starts without keyboard focus. Builds with Run In Background turned off pause whenever they do not have focus, which can look exactly like a stalled load: the splash screen sits there until somebody clicks the game. Browsers that throttle background tabs make it worse. Turn Run In Background on for WebGL builds you will publish on portals, and make sure your first screen invites a click.

7. The game's own loader is stuck, not Unity's

If Unity's bar finished and your game's own loading screen stops at a particular percentage, the engine is running and your code is waiting on something: a network request to a server that no longer exists, a login or SDK call that never returns in a browser, or an exception thrown in a coroutine. The console shows the exception. Test every build in a plain browser tab with no SDK credentials before you ship it, because that is how a portal's reviewer will first see it.

8. The browser ran out of memory

Phones give a web page far less memory than a desktop does. Large textures, uncompressed audio and big scenes can end the load with an "Out of memory" message or a silent tab reload. Use compressed texture formats, stream audio, keep the first scene light, and test on a mid-range Android phone rather than only on your development machine.

9. The wrong content type for .wasm

If .wasm files are served as application/octet-stream, browsers cannot use streaming compilation. Unity notices and falls back to a slower path, so the game usually still loads, just later than it should, and the console carries a warning about it. Serve .wasm as application/wasm.

A two-minute checklist before you upload anywhere

  1. Open the build from a real web server, not from the file system.
  2. Watch the Network tab for any 404, CORS or decoding error.
  3. Load it inside an iframe on another domain, the way portals will.
  4. Play past the first level, so anything loaded later is fetched too.
  5. Try it on a phone.

If your build passes all five, it is ready for portals. You can publish it on GameZone for free. We host Unity WebGL builds for developers, compressed ones included, and every developer gets a portfolio page.