{"record":{"id":"68ca82f9f1629eaf","repo":"dotnet/maui","slug":"opengl-dll-not-found","errorCode":null,"errorMessage":"OpenGL dll not found!","messagePattern":"OpenGL dll not found!","errorType":"exception","errorClass":"DllNotFoundException","httpStatus":null,"severity":"critical","filePath":"src/Compatibility/Core/src/GTK/Controls/GLWidget/X11/XWindowInfoInitializer.cs","lineNumber":73,"sourceCode":"\n\t\t\treturn retval;\n\t\t}\n\n\t\tprivate static IntPtr XGetVisualInfo(IntPtr display, XVisualInfoMask infoMask, ref XVisualInfo template, out int nitems)\n\t\t{\n\t\t\treturn XGetVisualInfoInternal(display, (IntPtr)(int)infoMask, ref template, out nitems);\n\t\t}\n\n\t\tprivate static IntPtr GetVisualInfo(GraphicsMode mode, IntPtr display, int screenNumber)\n\t\t{\n\t\t\ttry\n\t\t\t{\n\t\t\t\tint[] attributes = CreateAttributeList(mode).ToArray();\n\t\t\t\treturn glXChooseVisual(display, screenNumber, attributes);\n\t\t\t}\n\t\t\tcatch (DllNotFoundException e)\n\t\t\t{\n\t\t\t\tthrow new DllNotFoundException(\"OpenGL dll not found!\", e);\n\t\t\t}\n\t\t\tcatch (EntryPointNotFoundException enf)\n\t\t\t{\n\t\t\t\tthrow new EntryPointNotFoundException(\"Glx entry point not found!\", enf);\n\t\t\t}\n\t\t}\n\n\t\tprivate static List<int> CreateAttributeList(GraphicsMode mode)\n\t\t{\n\t\t\tList<int> attributeList = new List<int>(24);\n\n\t\t\tattributeList.Add((int)GLXAttribute.RGBA);\n\n\t\t\tif (mode.Buffers > 1)\n\t\t\t{\n\t\t\t\tattributeList.Add((int)GLXAttribute.DOUBLEBUFFER);\n\t\t\t}\n","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/dotnet/maui/blob/f377ff1c5ee04d334d8a925f50c83a6b7afddf03/src/Compatibility/Core/src/GTK/Controls/GLWidget/X11/XWindowInfoInitializer.cs#L55-L91","documentation":"XWindowInfoInitializer.GetVisualInfo P/Invokes glXChooseVisual to obtain an X11 visual for OpenGL. If the native OpenGL shared library (typically libGL.so) cannot be located/loaded, the P/Invoke raises DllNotFoundException, which this code catches and re-throws with the message 'OpenGL dll not found!' wrapping the original.","triggerScenarios":"Running the GLWidget-based GTK control on an X11/Linux system where libGL.so is absent, not on the loader path, or inaccessible. Common on minimal containers, headless servers, or systems with only software rendering.","commonSituations":"Missing OpenGL runtime (Mesa/libGL) on a Linux desktop or container; running in a Wayland-only session without the GLX compatibility shim; deployment to a slim Docker image lacking libgl1/mesa packages; LD_LIBRARY_PATH not including the GL library directory.","solutions":["Install the OpenGL runtime: `apt-get install libgl1 mesa-libgl` (or the distro equivalent mesa packages).","Ensure X11/GLX is available (Xvfb or a real X server) — pure Wayland without XWayland GLX may not suffice.","Set LD_LIBRARY_PATH or configure the loader so libGL.so is discoverable.","Verify with `glxinfo | grep 'OpenGL renderer'` that a renderer is present."],"exampleFix":"# before — missing GL on Debian/Ubuntu container\n# (control throws 'OpenGL dll not found!')\n# after\nsudo apt-get update && sudo apt-get install -y libgl1 mesa-utils\nglxinfo | grep 'OpenGL renderer'  # confirm a renderer exists","handlingStrategy":"try-catch","validationCode":"static bool HasOpenGL()\n{\n    try { foreach (var n in new[] { \"libGL.so.1\", \"libGL.so\" })\n        { if (System.Runtime.InteropServices.NativeLibrary.TryLoad(n, out _)) return true; } }\n    catch { }\n    return false;\n}","typeGuard":null,"tryCatchPattern":"try { /* construct GLWidget */ }\ncatch (DllNotFoundException ex) when (ex.Message.Contains(\"OpenGL\"))\n{ /* prompt user to install libgl1/mesa; disable GL surface */ }","preventionTips":["Install libgl1/mesa in Linux deploy images.","Verify with `glxinfo` at deploy time.","Run under a real X server or XWayland with GLX.","Document native-library prerequisites for GTK GLWidget."],"tags":["gtk","opengl","x11","native-library","linux","glwidget","maui-compat"],"backgroundTag":null,"analyzedSha":"f377ff1c5ee04d334d8a925f50c83a6b7afddf03","analyzedAt":"2026-08-13T14:26:18.069Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}