Why does my Godot headless server fail to start?

Run with --headless --rendering-driver dummy. Use the Linux/Server export template. Without dummy renderer, server tries to open a display.

Download via Editor → Manage Export Templates. Pick Linux Server 4.x. Smaller binary; no rendering drivers compiled in.

Common pattern: Alpine + Godot server template. Mount export, run godot --headless --main-pack game.pck.

Fix: Godot Headless Server Won't Start

Quick answer: Use Linux Server export template. Run with --headless --rendering-driver dummy.

Server fails on a headless box: “couldn’t open display.” Default rendering wants a display.

The Fix

# Editor → Manage Export Templates → Download Linux Server

# Run
$ ./mygame.x86_64 --headless --rendering-driver dummy --main-pack mygame.pck

# Or via Docker
FROM alpine:3
RUN apk add libstdc++
COPY mygame.x86_64 mygame.pck /app/
WORKDIR /app
CMD ["./mygame.x86_64", "--headless", "--rendering-driver", "dummy"]

Server template skips rendering. dummy driver bypasses display attempts. Headless flag suppresses other UI.

Verifying

Server starts on a display-less box. Player connects via TCP. Rendering disabled.

“Server template. Headless. Dummy driver.”

Related Issues

For Web COEP, see COEP. For macOS notarize, see notarize.

Server template. Dummy driver.