Comfy-Org/ComfyUI · error · RuntimeError

eglBindAPI(EGL_OPENGL_ES_API) failed

Error message

eglBindAPI(EGL_OPENGL_ES_API) failed

What it means

Raised during GLSL renderer initialization when eglBindAPI(EGL_OPENGL_ES_API) returns false after an EGL display was successfully obtained. The display enumerated fine, but the EGL driver refused to bind OpenGL ES as the rendering API — typically a driver/library mismatch (e.g., a GLES-incompatible EGL implementation, missing libGLESv2, or mixed glvnd/non-glvnd libraries).

Source

Thrown at comfy_extras/nodes_glsl.py:257

        return cls._instance

    def __init__(self):
        if GLContext._initialized:
            return

        import time
        start = time.perf_counter()

        self._display = None
        self._surface = None
        self._context = None
        self._vao = None

        try:
            self._display, self._egl_major, self._egl_minor = _get_egl_display()

            if not EGL.eglBindAPI(EGL.EGL_OPENGL_ES_API):
                raise RuntimeError("eglBindAPI(EGL_OPENGL_ES_API) failed")

            config = EGL.EGLConfig()
            n_configs = ctypes.c_int32(0)
            if not EGL.eglChooseConfig(
                self._display,
                _egl_attribs(
                    EGL.EGL_RENDERABLE_TYPE, EGL.EGL_OPENGL_ES3_BIT,
                    EGL.EGL_SURFACE_TYPE, EGL.EGL_PBUFFER_BIT,
                    EGL.EGL_RED_SIZE, 8, EGL.EGL_GREEN_SIZE, 8,
                    EGL.EGL_BLUE_SIZE, 8, EGL.EGL_ALPHA_SIZE, 8,
                ),
                ctypes.byref(config), 1, ctypes.byref(n_configs),
            ) or n_configs.value == 0:
                raise RuntimeError("eglChooseConfig() failed")

            self._surface = EGL.eglCreatePbufferSurface(
                self._display, config,
                _egl_attribs(EGL.EGL_WIDTH, 64, EGL.EGL_HEIGHT, 64),

View on GitHub (pinned to 1c6d8d45b3)

Solutions

  1. Install the GLES runtime: libgles2 / libgles3 and matching libegl-mesa0 (or vendor equivalents).
  2. Reinstall/align the GPU driver stack so EGL and GLES libraries come from the same vendor version.
  3. Verify outside ComfyUI with a minimal eglBindAPI test or eglinfo -B to confirm GLES support.
  4. As a last resort on problematic hosts, run under a software path (llvmpipe/Mesa softpipe) to confirm the pipeline, then fix the driver.

Example fix

# debian/ubuntu: ensure GLES + EGL agree
apt-get install -y libegl1 libegl-mesa0 libgles2 libglesv2-c2 mesa-utils
eglinfo -B   # should list an OpenGL ES platform
Defensive patterns

Strategy: try-catch

Validate before calling

import ctypes
from OpenGL import EGL

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

Try / catch

try:
    renderer = GlslRenderer()
except RuntimeError as e:
    if 'eglBindAPI' in str(e):
        install_gles_runtime()  # libgles2/libglesv2 + matching libegl
        renderer = GlslRenderer()
    else:
        raise

Prevention

When it happens

Trigger: Initializing the GLSL context on a system whose EGL implementation does not support the OpenGL ES API: missing libGLESv2/libGLESv3, an EGL library from a different vendor than the GL libraries, or a broken glvnd setup. The display-init step succeeded, so this is specifically the API-bind stage failing.

Common situations: Containers with libEGL installed but no GLES libraries; mixing Mesa EGL with proprietary GL libs; partial driver upgrades leaving mismatched versions.

Related errors

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