Comfy-Org/ComfyUI · critical · RuntimeError

Failed to initialize EGL display. No display server and no h

Error message

Failed to initialize EGL display.
No display server and no headless EGL platform available.
Tried:
{details}
Ensure GPU drivers are installed or set DISPLAY for a virtual framebuffer.

What it means

Raised by _get_egl_display in the GLSL node after every display strategy failed: the default EGL display (X11/Wayland), the MESA surfaceless platform, and the ANGLE Vulkan platform all either returned no display or failed eglInitialize. The message lists per-strategy failure details. This is an environment problem — the machine has no usable EGL implementation for GPU-accelerated OpenGL ES, which the GLSL rendering node requires.

Source

Thrown at comfy_extras/nodes_glsl.py:189

    ]

    for name, platform, native_display, attribs in headless_strategies:
        display = _get_egl_platform_display_ext(platform, native_display, attribs)
        if not display:
            failures.append(f"{name}: eglGetPlatformDisplayEXT returned no display")
            continue
        major, minor = ctypes.c_int32(0), ctypes.c_int32(0)
        try:
            if EGL.eglInitialize(display, ctypes.byref(major), ctypes.byref(minor)):
                logger.info(f"Using EGL {name} platform (headless)")
                return display, major.value, minor.value
            failures.append(f"{name}: eglInitialize returned false")
        except Exception as e:
            failures.append(f"{name}: {e}")
            continue

    details = "\n".join(f"  - {f}" for f in failures)
    raise RuntimeError(
        "Failed to initialize EGL display.\n"
        "No display server and no headless EGL platform available.\n"
        f"Tried:\n{details}\n"
        "Ensure GPU drivers are installed or set DISPLAY for a virtual framebuffer."
    )


def _gl_str(name):
    """Get an OpenGL string parameter."""
    v = gl.glGetString(name)
    if not v:
        return "Unknown"
    if isinstance(v, bytes):
        return v.decode(errors="replace")
    return ctypes.string_at(v).decode(errors="replace")


def _detect_output_count(source: str) -> int:

View on GitHub (pinned to 1c6d8d45b3)

Solutions

Install EGL/GLES runtime packages: mesa-utils, libegl1, libgles2, and for NVIDIA the nvidia EGL ICD files (libnvidia-egl-wayland / nvidia egl-gbm vendor JSONs in /usr/share/glvnd/egl_vendor.d).
In containers, ensure the NVIDIA container toolkit exposes EGL libraries and the 10_nvidia.json ICD.
If an X server exists but DISPLAY is unset, export DISPLAY=:0 (or run under xvfb-run) so the default display strategy works.
Verify with eglinfo that a platform initializes before rerunning the node.

Example fix

# docker: add EGL/GLES runtime before running GLSL nodes
apt-get install -y libegl1 libgles2 libglvnd0 mesa-utils
# verify a headless platform initializes
eglinfo -B

Defensive patterns

Strategy: fallback

Validate before calling

import ctypes
from OpenGL import EGL

def egl_available() -> bool:
    d = EGL.eglGetDisplay(EGL.EGL_DEFAULT_DISPLAY)
    if not d:
        return False
    m, n = ctypes.c_int32(0), ctypes.c_int32(0)
    return bool(EGL.eglInitialize(d, ctypes.byref(m), ctypes.byref(n)))

Try / catch

try:
    renderer = GlslRenderer()
except RuntimeError as e:
    if 'Failed to initialize EGL' in str(e):
        raise RuntimeError('GLSL nodes need a working EGL stack; install GPU drivers / set DISPLAY') from e
    raise

Prevention

Provision headless hosts with Mesa EGL + GLES packages and vendor ICD JSONs.
In containers use the NVIDIA container toolkit so EGL libraries and ICDs are injected.
Set DISPLAY or run under xvfb when an X server exists.
Smoke-test with eglinfo -B before relying on GLSL nodes.

When it happens

Trigger: Running the GLSL node on a headless server/container without GPU drivers or without libEGL/Mesa installed; a container missing /usr/lib/x86_64-linux-gnu/libEGL and the surfaceless platform; a host with broken driver installation where eglInitialize fails on every platform.

Common situations: Docker images without mesa/EGL packages (e.g., slim CUDA images); headless cloud GPU instances with display-less driver installs; NVIDIA driver misconfiguration (nvidia-egl not installed, or container lacks the EGL ICD JSONs); SSH sessions without DISPLAY where surfaceless is unavailable.

Related errors

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/f7dc7dd082d4971c. Report an issue: GitHub.