// troubleshooting guide · defold

Defold HTML5 Build Black Screen

Status
Workaround available
platforms:
HTML5
updated:
November 18, 2026
reports:
5
Method
how we research
Share

RUNBOOK · defold/html5-black-screen5 FIXES

// quick answer

A black screen in a Defold web build usually comes from how it is served (needs a web server), browser zoom not at 100%, heap size, or render setup. Check the browser console first.

Most likely fix: Serve it from a web server

How to fix it

// try these in order, the most common fix is first

  1. FIX 1Serve it from a web server

    1. 01Use Project > Build HTML5 which starts a local server
    2. 02For a bundle, host it with a local web server instead of double-clicking index.html
    Did this fix it?
  2. FIX 2Open the browser console

    1. 01Press F12 and read the first error
    2. 02Search the exact message on the Defold forum
    Did this fix it?
  3. FIX 3Test at 100% zoom

    1. 01Press Ctrl/Cmd+0 and reload
    Did this fix it?
  4. FIX 4Raise the heap size

    1. 01Customize heap size as described in the HTML5 manual
    Did this fix it?
  5. FIX 5Isolate the render setup

    1. 01Try a minimal scene
    2. 02Compare custom shaders against defaults
    3. 03If it began after updating, try the previous engine version
    Did this fix it?

SANDBOX · defold RUNS IN YOUR BROWSER

Try it: open a 3D scene, render it and export a build

A hands-on Defold-style sandbox, including the spots where users get stuck. See where problems like this one start. 1-2 minutes, nothing is saved.

Symptoms

The game logo or loader appears, then the canvas stays black, sometimes with console errors.

Why it happens

  • C-01Bundle opened from file:// instead of a web server
  • C-02Browser zoom not 100% (fixed in 1.2.162 for one case)
  • C-03Heap size too small
  • C-04Custom render script or shadows that fail on WebGL
  • C-05Regression after an engine upgrade

// this guide also covers

  • defold html5 black screen
  • defold html5 not working
  • defold web build blank

Still not working?

If Defold keeps failing, you're not alone. See every Defold problem users report or the alternatives people switch to.

Have an app idea? Our small team builds any software: web and mobile apps, games, desktop, AI tools. Price agreed together.

Talk to us

Watch Defold Get an email when its price changes, it has an outage, or we publish a new fix. No spam.

Fixed it? Share this guide

The same problem in other apps

All export, render & quality loss guides →

Other Defold errors

All 11 Defold errors and fixes →