dotnet/maui · critical · DllNotFoundException

OpenGL dll not found!

Error message

OpenGL dll not found!

What it means

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.

Source

Thrown at src/Compatibility/Core/src/GTK/Controls/GLWidget/X11/XWindowInfoInitializer.cs:73

			return retval;
		}

		private static IntPtr XGetVisualInfo(IntPtr display, XVisualInfoMask infoMask, ref XVisualInfo template, out int nitems)
		{
			return XGetVisualInfoInternal(display, (IntPtr)(int)infoMask, ref template, out nitems);
		}

		private static IntPtr GetVisualInfo(GraphicsMode mode, IntPtr display, int screenNumber)
		{
			try
			{
				int[] attributes = CreateAttributeList(mode).ToArray();
				return glXChooseVisual(display, screenNumber, attributes);
			}
			catch (DllNotFoundException e)
			{
				throw new DllNotFoundException("OpenGL dll not found!", e);
			}
			catch (EntryPointNotFoundException enf)
			{
				throw new EntryPointNotFoundException("Glx entry point not found!", enf);
			}
		}

		private static List<int> CreateAttributeList(GraphicsMode mode)
		{
			List<int> attributeList = new List<int>(24);

			attributeList.Add((int)GLXAttribute.RGBA);

			if (mode.Buffers > 1)
			{
				attributeList.Add((int)GLXAttribute.DOUBLEBUFFER);
			}

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Install the OpenGL runtime: `apt-get install libgl1 mesa-libgl` (or the distro equivalent mesa packages).
2. Ensure X11/GLX is available (Xvfb or a real X server) — pure Wayland without XWayland GLX may not suffice.
3. Set LD_LIBRARY_PATH or configure the loader so libGL.so is discoverable.
4. Verify with `glxinfo | grep 'OpenGL renderer'` that a renderer is present.

Example fix

# before — missing GL on Debian/Ubuntu container
# (control throws 'OpenGL dll not found!')
# after
sudo apt-get update && sudo apt-get install -y libgl1 mesa-utils
glxinfo | grep 'OpenGL renderer'  # confirm a renderer exists

static bool HasOpenGL()
{
    try { foreach (var n in new[] { "libGL.so.1", "libGL.so" })
        { if (System.Runtime.InteropServices.NativeLibrary.TryLoad(n, out _)) return true; } }
    catch { }
    return false;
}

try { /* construct GLWidget */ }
catch (DllNotFoundException ex) when (ex.Message.Contains("OpenGL"))
{ /* prompt user to install libgl1/mesa; disable GL surface */ }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Glx entry point not found!
• MinimumDate must be lower than MaximumDate
• MaximumDate must be greater than MinimumDate
• call Forms.Init() before this
• call GtkThemes.Init() before this

AI-assisted analysis of dotnet/maui@f377ff1c5e (2026-08-13). Data as JSON: /api/errors/68ca82f9f1629eaf. Report an issue: GitHub.