Why does my Godot HTML5 export show a black screen?

A black screen typically means the WebGL context was created but the game failed to load resources. Check your browser console for CORS errors on .pck or .wasm files. Ensure all game files are served from the same origin or with proper CORS headers, and that the .pck file is accessible at the expected URL path.

Can I test Godot web exports locally?

Yes, but you cannot open the HTML file directly (file:// protocol will not work). Use a local web server that sends the correct headers. Python's http.server works for basic testing, but you need to add COOP/COEP headers for SharedArrayBuffer support. Alternatively, use the Godot editor's built-in HTTP server for testing web exports.

Fix: Godot HTML5/Web Export Showing White or Black Screen

Quick answer: A white screen usually means the browser blocked SharedArrayBuffer because the required HTTP headers are missing. You need to serve the page with 'Cross-Origin-Opener-Policy: same-origin' and 'Cross-Origin-Embedder-Policy: require-corp' headers.

Here is how to fix Godot html5 web export white black screen. You export your Godot 4 project for the web, upload it to your server, open it in a browser, and get nothing — just a white screen, a black screen, or an endlessly spinning loading indicator. The game worked perfectly in the editor. This is one of the most frustrating Godot web export issues because the cause is almost always outside of Godot itself: it lives in how your web server is configured.

The Symptom

After exporting your Godot 4 project with the Web export preset and deploying the files to a web server, you see one of the following when opening the page in a browser:

White screen — The page loads but nothing renders. The browser console may show errors about SharedArrayBuffer not being defined or a security policy violation.
Black screen — The WebGL canvas appears but stays black. The console may show errors about failed resource loading, CORS violations, or a .pck file that could not be fetched.
Infinite loading — The Godot splash screen or loading bar appears but never finishes, eventually timing out or crashing the tab.

Opening the browser’s developer console (F12) is critical here. The error messages in the console will tell you exactly which variant of this problem you are dealing with.

What Causes This

Godot 4 web exports use SharedArrayBuffer for multi-threaded WebAssembly execution. Browsers require two specific HTTP headers to enable SharedArrayBuffer, and they require the page to be served over HTTPS (or localhost). If either condition is missing, the browser silently refuses to allocate shared memory, and the Godot engine fails during initialization — resulting in a white screen.

The two required headers are:

Cross-Origin-Opener-Policy: same-origin (COOP)
Cross-Origin-Embedder-Policy: require-corp (COEP)

These headers create a “cross-origin isolated” context that gives the page access to SharedArrayBuffer and high-resolution timers. Most web servers do not send these headers by default, which is why the export works locally in Godot’s built-in server but breaks on your production hosting.

The black screen variant typically occurs when the WebGL context initializes successfully but the game’s .pck file, .wasm binary, or other assets fail to load. This is usually a CORS issue — if your assets are served from a CDN or different subdomain without proper Access-Control-Allow-Origin headers, the browser blocks the fetch and the game has no data to render.

The infinite loading variant often happens when the .pck file path is wrong. The HTML shell tries to fetch the pack file at a relative URL, and if your deployment changes the directory structure, the fetch returns a 404 that the loader interprets as a slow download rather than a missing file.

The Fix

Step 1: Add the COOP and COEP headers to your web server.

The configuration depends on your server. Here are the most common setups:

# Apache (.htaccess)
Header set Cross-Origin-Opener-Policy "same-origin"
Header set Cross-Origin-Embedder-Policy "require-corp"

# Nginx (inside your server or location block)
add_header Cross-Origin-Opener-Policy "same-origin" always;
add_header Cross-Origin-Embedder-Policy "require-corp" always;

# Caddy (Caddyfile)
header Cross-Origin-Opener-Policy "same-origin"
header Cross-Origin-Embedder-Policy "require-corp"

If you are hosting on a static site platform like Netlify, Vercel, or Cloudflare Pages, add these headers via the platform’s configuration file:

# Netlify (_headers file in your publish directory)
/*
  Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp

# Vercel (vercel.json)
{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "Cross-Origin-Opener-Policy", "value": "same-origin" },
        { "key": "Cross-Origin-Embedder-Policy", "value": "require-corp" }
      ]
    }
  ]
}

Step 2: Ensure HTTPS is active.

SharedArrayBuffer is only available in secure contexts. This means your game must be served over HTTPS or from localhost. If you are testing on a remote server over plain HTTP, the browser will block SharedArrayBuffer even if the headers are present. Most hosting platforms provide free HTTPS via Let’s Encrypt, so enable it if you have not already.

Step 3: Disable thread support as a fallback.

If you cannot configure the required headers — for example, if you are hosting on a platform that does not support custom headers — you can disable threading in the export preset. In the Godot editor, open the Web export preset and uncheck Thread Support. This produces a single-threaded build that does not require SharedArrayBuffer:

# In the Export dialog:
# Web export preset → Options
# Uncheck "Thread Support"
# This removes the SharedArrayBuffer requirement
# but may reduce performance for CPU-heavy games

Note that disabling threads means your game runs single-threaded in the browser, which can cause frame drops in CPU-intensive scenes. Use this as a fallback, not a preferred solution.

Step 4: Fix CORS and asset paths.

If your screen is black rather than white, check the browser console for 404 errors or CORS blocks on .pck, .wasm, or .js files. Ensure all game files are in the same directory as the HTML file and served from the same origin. If you use a CDN, add Access-Control-Allow-Origin: * to the CDN’s response headers for these file types.

Also verify that the .pck file name matches what the HTML shell expects. Godot generates the HTML with a specific pack file name based on your export preset name. If you rename files after export, the loader will not find them.

Why This Works

The COOP and COEP headers tell the browser that the page opts into cross-origin isolation. This is a security mechanism introduced by browser vendors to prevent Spectre-class side-channel attacks. SharedArrayBuffer was disabled by default in all major browsers after the Spectre vulnerability was disclosed, and it is only re-enabled when the page proves it is isolated from cross-origin resources.

Godot 4’s web export uses SharedArrayBuffer to share memory between the main thread and web workers, which is how it achieves multi-threaded performance in the browser. Without it, the engine cannot initialize its threading subsystem and fails before rendering the first frame.

The HTTPS requirement exists because secure contexts are a prerequisite for cross-origin isolation. Browsers will not honor COOP/COEP headers on insecure origins (except localhost, which is treated as a special case for developer convenience).

Related Issues

If your web export loads but is missing textures, audio, or other resources, see Fix: Godot Exported Game Missing Resources or Showing Errors for guidance on export filters and resource inclusion.

If the exported game works in the browser but crashes with PCK-related errors on desktop platforms, check Fix: Godot PCK File Not Found Error After Export.

For custom fonts or assets that load in the editor but fail in exported builds, see Fix: Custom Fonts or Assets Not Loading in Godot Exported Build.

Two headers. One secure connection. Game plays in the browser.