Comfy-Org/ComfyUI · error · RuntimeError

eglCreatePbufferSurface() failed

Error message

eglCreatePbufferSurface() failed

What it means

Raised during one-time initialization of the GLContext singleton in the GLSL render nodes. After eglChooseConfig() succeeds with a pbuffer-capable GLES3 config, eglCreatePbufferSurface() is asked for a tiny 64x64 offscreen surface to keep the context current; the driver refused it and returned EGL_NO_SURFACE. This is an environment/driver problem, not a workflow problem: the selected EGL implementation cannot back a pbuffer surface with the chosen config.

Source

Thrown at comfy_extras/nodes_glsl.py:278

            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),
            )
            if not self._surface:
                raise RuntimeError("eglCreatePbufferSurface() failed")

            self._context = EGL.eglCreateContext(
                self._display, config, EGL.EGL_NO_CONTEXT,
                _egl_attribs(EGL.EGL_CONTEXT_CLIENT_VERSION, 3),
            )
            if not self._context:
                raise RuntimeError("eglCreateContext() failed")

            if not EGL.eglMakeCurrent(self._display, self._surface, self._surface, self._context):
                raise RuntimeError("eglMakeCurrent() failed")

            self._vao = gl.glGenVertexArrays(1)
            gl.glBindVertexArray(self._vao)

        except Exception:
            self._cleanup()
            raise

View on GitHub (pinned to 1c6d8d45b3)

Solutions

  1. Verify EGL/GLES drivers: install libegl1/libegl-mesa0 and libgles2 (Debian/Ubuntu) or the matching NVIDIA headless driver package.
  2. Check that the selected EGL vendor actually supports pbuffers: run eglinfo and confirm a config with EGL_SURFACE_TYPE=EGL_PBUFFER_BIT and EGL_RENDERABLE_TYPE=EGL_OPENGL_ES3_BIT exists.
  3. If using NVIDIA, ensure the EGL vendor library is the one loaded (check /usr/share/glvnd/egl_vendor.d/10_nvidia.json and that the GPU is accessible, e.g. nvidia-smi works in the container).
  4. On a truly GPU-less host, use a software EGL (Mesa llvmpipe) so pbuffer creation succeeds.
  5. If no working EGL stack is available, avoid the GLSL nodes and use equivalent PyTorch-based image nodes instead.
Defensive patterns

Strategy: validation

Validate before calling

# Run before any GLSL node executes, in the same process/env:
import ctypes
EGL = ctypes.CDLL("libEGL.so.1")
EGL.eglGetDisplay.argtypes = [ctypes.c_void_p]
dpy = EGL.eglGetDisplay(ctypes.c_void_p(0))
if not EGL.eglInitialize(dpy, None, None):
    raise RuntimeError("No usable EGL display — GLSL nodes will fail at eglCreatePbufferSurface")

Try / catch

try:
    run_glsl_node()
except RuntimeError as e:
    if "eglCreatePbufferSurface" in str(e):
        raise RuntimeError("GL/EGL driver cannot create offscreen surfaces; fix the EGL stack (install libegl-mesa/libgles, fix NVIDIA EGL vendor) or avoid GLSL nodes") from e
    raise

Prevention

When it happens

Trigger: First execution of any GLSL node (e.g. the fragment-shader render node) in a headless process where the EGL vendor library advertises GLES3 renderable configs but cannot actually create pbuffer surfaces; mixed-driver setups (NVIDIA GL + Mesa EGL or vice versa); remote/headless servers with no accessible GPU and a broken EGL fallback; ANGLE/driver mismatch where eglChooseConfig picked a config whose surface type is not truly supported.

Common situations: Running ComfyUI in a Docker container or SSH session without libegl-mesa/libgles installed correctly; NVIDIA headless drivers missing libnvidia-egl-wayland or EGL vendor config; X-forwarding setups where EGL default display has no pbuffer support.

Related errors

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