Fix Unity WebGL Not Loading: Common Errors

When your Unity WebGL not loading problem shows up as a frozen loading bar, a black screen, or a browser console full of red, the cause is almost always one of five things: a broken file path, a compression mismatch, a memory ceiling, a CORS block, or a graphics/WebGL context failure. This guide walks through each one in the order you should check them, so you can get your browser build running instead of guessing.

Step 1: Open the browser console first

Before you change a single setting, press F12 and read the Console and Network tabs. Nearly every WebGL failure prints a real reason there, and fixing the wrong thing wastes hours.

• A red 404 in the Network tab means a file the loader wants is missing or misnamed — usually the .data, .wasm, or .framework.js file.
• Unable to parse Build/xxx.framework.js.gz means the server is sending a compressed file but not the header that tells the browser to decompress it.
• Uncaught RangeError: Maximum call stack or Out of memory points at the memory ceiling.
• Cross-Origin Request Blocked is a CORS problem, covered below.

Read the exact string. It tells you which section of this article to jump to.

Step 2: Fix the "loaded from file://" black screen

The single most common Unity WebGL black screen is caused by double-clicking index.html and opening it as a file:// URL. Modern browsers block WebAssembly and fetch requests over file:// for security, so the loader silently dies.

WebGL builds must be served over HTTP. To test locally, run a tiny web server from your build folder:

1. Open a terminal in the build output folder.
2. Run python -m http.server 8000 (Python 3) or npx serve.
3. Open http://localhost:8000 in your browser.

If the game loads over http://localhost but not by double-click, the file path was the whole problem — nothing else was wrong.

Step 3: Solve the compression mismatch (Brotli/Gzip)

Unity ships builds with Brotli or Gzip compression by default. The browser only accepts these if the server returns the right Content-Encoding header. When it doesn't, you get the Unable to parse ... .br / .gz error and a stalled bar.

You have two clean fixes:

• Configure the server. Add the headers so .br files return Content-Encoding: br and .wasm returns Content-Type: application/wasm. On Apache this is a .htaccess rule; on Nginx it is gzip_static/brotli_static.
• Or switch to a decompression fallback. In Player Settings → Publishing Settings, enable Decompression Fallback. Unity then embeds a JS decompressor so the build works even on a dumb static host that sends no encoding headers. This costs a little load time but removes the whole class of bug.

If you host on a platform that already handles Unity headers for you, you skip this step entirely — which is exactly why publishing to a purpose-built host beats a random static bucket.

Step 4: Fix WebGL memory errors

Out of memory or a crash partway through loading means your build asked for more memory than the tab could give it. This is common on mobile browsers, which cap a single tab far lower than desktop.

• In Player Settings → Resolution and Presentation / Publishing, review the Memory Size and enable a growable heap rather than a huge fixed allocation.
• Shrink the actual payload. Oversized textures and uncompressed audio are the usual culprits. Our guide on reducing your Unity WebGL build size covers texture compression, stripping engine code, and audio settings that directly lower the memory footprint.
• Test in an incognito window with no other heavy tabs open — extensions and other tabs eat the same memory pool.

Step 5: Clear CORS and MIME blocks

If the console shows Cross-Origin Request Blocked or the .wasm file loads as text/html, the browser is refusing files the server described incorrectly.

• Make sure every build file is served with the correct MIME type: .wasm → application/wasm, .js → application/javascript, .data → application/octet-stream.
• If your game HTML and your build files live on different domains or a CDN, add Access-Control-Allow-Origin headers on the file host.
• WebAssembly streaming compilation needs application/wasm; without it some browsers fall back to a slower path or fail outright.

Step 6: Rule out the WebGL context itself

If the loader finishes but you still get a black canvas, the GPU context may have failed. Visit chrome://gpu to confirm hardware acceleration is on, update graphics drivers, and test in a second browser. A build that works in Chrome but not an old in-app webview usually means the target simply lacks WebGL 2 support — set the fallback to WebGL 1 in Player Settings → Other Settings → Graphics APIs if you must support old devices.

Get your build online the easy way

Most of these errors come from hosting a WebGL build on infrastructure that was never set up for it. If you would rather write your game than tune server headers, publish it on The Gaming Nest: upload your Unity or Godot WebGL build and we serve it with the right compression, MIME, and CORS headers so players click and play instantly in the browser — no downloads. New to exporting? Start with our walkthrough on exporting a Unity WebGL build, then publish your game and share the link.