My Godot Game Works in the Editor. Why Is the Web Export Broken?

Your game runs in Godot, but the browser shows a blank page, stops at the loading screen, or loses an effect after you upload it. Start by finding where it fails. A missing file, a hosting requirement, and a shader error need different fixes.

What do you see when it fails?

• The HTML page never opens: check the URL and whether the host can find index.html.
• The page opens but loading fails: inspect the browser Console and Network panels for the first error or failed file request.
• The game starts but an object or effect is missing: compare the same scene with a plain material and inspect shader errors.
• The game plays but sound or saved progress behaves differently: test browser permissions and storage separately from startup.

Write down the first error before changing anything. If you change the renderer, export options, hosting settings, and shaders in one attempt, a successful reload will not tell you which change mattered.

Make a small export you can compare

For a basic Godot 4 browser test, use GDScript and Compatibility rendering. The web target requires WebGL 2.0; Forward+ and Mobile are not web rendering options. The stable documentation checked on September 8, 2026 still excludes Godot 4 C# projects from web export.

Install export templates matching your editor version, then add a Web preset under Project > Export. Export the runnable project, not only its resource pack. If the dialog reports a missing template or invalid configuration, resolve that message before investigating the host.

For this comparison, leave Thread Support and Extensions Support off if the project does not need them. Export as index.html into a fresh directory outside the project. Keep all generated files together and do not rename them afterward.

Use a copy of our tiny coin game if your main project has too many dependencies. Record the editor version and export options. A working small game on the same host helps you separate project-specific problems from upload problems.

Did you open the HTML file directly?

Run the export through a local HTTP server. With Python 3 installed, open a terminal inside the directory containing index.html and run:

python3 -m http.server 8000 --bind 127.0.0.1

On Windows, use py -3 in place of python3 if that is how Python is installed. Open http://127.0.0.1:8000/index.html. Leave the terminal running while testing; Ctrl+C stops it. If port 8000 is busy, choose another port and change the browser address too.

Compare the result with the uploaded game using the same browser. If both fail with the same error, work on that error first. If only the uploaded copy fails, compare its requested files and response headers with the local copy.

The loading bar stops, or a file cannot be fetched

Open the browser developer tools from its menu. In Network, reload the page and select the failed request. Check the full request URL, status, response headers, and response body. Chrome also provides Disable cache while DevTools is open, which helps compare a fresh request with a cached one.

• 404 or 403: compare the requested filename and directory with the files you uploaded. Check capitalization as well as spelling.
• 200, but the response is your website homepage: the host returned HTML for an asset URL. Check whether a catch-all route sends missing game files to the site’s index page.
• A WebAssembly MIME error: inspect the .wasm response. Streaming compilation expects Content-Type: application/wasm. A correct header on index.html does not fix the .wasm response.
• A JavaScript or WebAssembly parser error after a new upload: check that the HTML, JavaScript, .wasm, and game pack came from the same export. Replace the export as a complete set.

A successful status code alone is not enough. For example, if a request for index.wasm returns text beginning with an HTML document, changing the game’s player script cannot fix that response. Correct the file path or hosting rule, then request the file again.

If an older build keeps appearing, compare a fresh browser profile before deleting anything. Clear site data only for your test copy when needed; doing so can remove saved progress as well as caches. If you enabled a PWA, include its service worker in the investigation. Godot’s PWA export can cache a previously loaded game for offline use.

SharedArrayBuffer or cross-origin isolation errors

First check the actual preset you exported. Godot’s Thread Support and Extensions Support require cross-origin isolation. If neither feature is needed, disable both and make a fresh export. A false crossOriginIsolated value is not itself a failure for that simpler build.

For a build that needs isolation, use HTTPS on the public host and inspect the response headers for the game document. A common configuration is:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

These are HTTP response headers configured at the host, not HTML meta tags. The embedder policy also affects other resources the page loads. Cross-origin files may need CORS or resource-policy cooperation, and embedded games can have additional permissions constraints. Copying two headers without checking the actual response is not a complete diagnosis.

In the developer-tools Console, select the game frame if it is embedded, then evaluate:

window.crossOriginIsolated

For the isolated build, expect true. If it is false, inspect that frame’s hosting and embedding policies. Do not add strict isolation headers across an unrelated article or advertising site to fix one game. Test the game on its own hosting page first. See MDN’s isolation reference for the document and permissions requirements.

It works locally but fails on itch.io

Upload one ZIP containing the whole web export, with index.html at its root. Choose HTML Game as the project kind. Godot exports multiple files, so uploading only the HTML file is insufficient. The archive should open directly onto the exported files, not another folder you must enter first.

game.zip
  index.html
  index.js
  index.wasm
  index.pck
  ...the other files generated by this export

Treat that list as an illustration, not a filter for deciding which files to keep. Preserve every generated file. itch.io uses case-sensitive filenames and serves games from a subdirectory. In a custom HTML shell, relative asset paths stay within that directory; a path starting with / points elsewhere on the host.

Preview the uploaded game. Check the first failed request again instead of repeatedly rebuilding the ZIP. Keep the successful local export until the hosted copy works. If your game needs threads or extensions, confirm the hosted frame’s isolation status using the previous section. The itch.io upload guide explains packaging and embed options.

The game loads, but my shader disappears

A reader reported broken shaders in a Compatibility web export. The discussion did not include the shader code, so it cannot establish a specific engine bug or fix. It does identify a useful test: isolate the effect from the rest of the scene.

• In a copy of the scene, give the affected object a plain material. Export again with the same preset.
• If the object appears, restore the shader with its smallest visible effect. Add its original operations and texture inputs back separately.
• Save the first shader compilation error from the browser Console. Record the browser, device, renderer, and exact Godot version.
• Compare the same exported files in another supported browser. Record any difference before changing the shader again.

An editor preview is only one comparison point. For the rendering choices behind your scene, use the Godot renderer guide. If plain materials are also too dark, check the scene with our lighting and materials exercise before assuming that export broke the shader.

Sound or saves fail after the game starts

For silent audio, try an explicit click or tap on a Start button. Browsers can block audio that begins without user interaction. Keep that test separate from whether the sound file loaded successfully; a missing file needs a different fix.

For persistence, compare a normal browser session with the mode that failed. Private browsing and storage policies can change retention, and browser-managed data can be cleared or evicted. Saving successfully once does not establish that progress will survive every later visit. The save-system guide covers file validation and loading; browser retention needs its own test.

Make the next bug report reproducible

Before asking for help, fill in this small report. Leave unknown fields as unknown. An exact error and a failing file request usually give someone more to work with than a screenshot of an empty game window.

Godot version and edition:
Browser version, device, and OS:
Renderer:
Thread Support / Extensions Support / PWA:
Local HTTP test result:
Hosted test result:
First Console error:
Failed request URL, status, and Content-Type:
Steps to reproduce:
Expected result:
Actual result:

Share only public URLs and remove tokens or private paths from logs. Once the fix works, test one fresh load, a complete round, and a reload. If the game saves progress, close and reopen it too. Record which browser and host passed so the next export has a useful comparison.