Diagnosing LÖVE White Screen and Startup Crashes at main.lua Initialization

The problem you see

A LÖVE game opens to a blank white window, freezes, or closes immediately. The useful takeaway is that LÖVE only reaches the render loop after love.load finishes without error. If love.load fails, throws, or never returns, you get a white screen or silent crash with no draw call.

Recognizable conditions

• White window, no content, responsive to close: window created, love.load started but errored before the first draw.
• Window flashes then exits: fatal error during initialization, often a syntax error or missing main.lua.
• Window hangs with high CPU: infinite loop or blocking I/O inside love.load.
• Works on Windows, fails on Linux/macOS: case-sensitive path mismatch.

Cause and diagnostic table

Ordered checks

1. Verify entry point location

LÖVE requires main.lua at the root of the game directory or inside a .love zip. It is not searched recursively.

Check: list the top-level files. You should see main.lua alongside asset folders, not inside src/main.lua.

Fix if missing: move main.lua to root. Risk: changing folder layout may break relative paths used elsewhere.

2. Expose console output

On Windows the console is hidden by default. Launch from a terminal to see Lua errors.

# run from the game folder, no elevated permissions needed
# Windows PowerShell
love .

# macOS / Linux terminal
./love .

Expected check: the terminal stays open and shows a Lua stack trace if an error occurs. If you see no output, the failure is pre-Lua, e.g. missing main.lua.

3. Isolate love.load

Insert lightweight prints at the boundaries of love.load to see how far execution reaches.

function love.load()
    print('load start')
    -- existing code
    print('load end')
end

Run via terminal. If you see load start but not load end, the failure is inside love.load. If you see neither, the error is before love.load is called.

4. Audit asset loads

Common offenders are love.graphics.newImage and love.audio.newSource with incorrect paths.

Check: paths are relative to the root, use forward slashes, and match case exactly. On case-sensitive filesystems Assets/Player.png differs from assets/player.png.

Fix: normalize paths and verify files exist at the stated location. For large loads, move work out of love.load or add a loading screen to avoid appearing as a hang.

5. Check for blocking loops

Search love.load for while loops without exit conditions and for synchronous loading of many large assets.

Fix: replace blocking loops with incremental loading in love.update, or reduce the initial asset set.

Fixes tied to findings

• Missing main.lua: place the file at root, rebuild the .love archive if distributing.
• Syntax error: fix the Lua syntax, then relaunch from terminal to confirm no parse error.
• Bad asset path: correct case and relative path, verify the file exists.
• Hang: add an early print, split the load, or add progress feedback.

Escalation criteria

Escalate for human review if:

• The console shows no Lua error and main.lua is present, but the window still fails to create. This may indicate a build or dependency issue outside Lua code.
• Errors persist after correcting paths on a case-sensitive OS, suggesting a custom build or LuaJIT incompatibility.
• Behavior differs between LÖVE versions and cannot be reproduced with a minimal main.lua containing only function love.load() end.

Limitations and verification

This guide assumes standard LÖVE boot behavior where love.load is the first user callback. Current verification is required for specific LÖVE releases, as console handling and error presentation can change between versions. Practical verification is to run a minimal project with a known-good main.lua and confirm the terminal shows the load start/end prints and the window renders.