unoplatform/uno · error · NullReferenceException

Couldn't find GLibrary in WebKitGtkSharp

Error message

Couldn't find GLibrary in WebKitGtkSharp

What it means

X11NativeWebView (Skia WebView on Linux/X11) reflects into the WebKitGtkSharp assembly to patch GLibrary so that libwebkit2gtk-4.1.so is pre-loaded before WebKitGtk# dlopens 4.0. It does `Assembly.Load("WebKitGtkSharp").GetType("GLibrary")` and throws NullReferenceException when the type is absent. This is a coupling to a private implementation detail of WebKitGtkSharp: if the package is upgraded/changed so that GLibrary is renamed or removed, the patch can no longer find its anchor.

Source

Thrown at src/AddIns/Uno.UI.WebView.Skia.X11/X11NativeWebView.cs:99

				}
			}

			// webkit2gtk-4.1 adds support for exposing libsoup objects, most importantly in webkit_uri_request_get_http_headers.
			// Gtk# by default loads libwebkit2gtk-4.0 (+ libsoup-2.0), but we want libwebkit2gtk-4.1 (+ libsoup-3.0), so what
			// we do is that before WebKitGtk# makes its dlopen calls, we load libwebkit2gtk-4.1 and put it where the handle to
			// libwebkit2gtk-4.0 will be expected to be, so that when WebKitGtk# attempts to dlopen(libwebkit2gtk-4.0), it will
			// find the handle already there and will just use it instead.
			if (!NativeLibrary.TryLoad("libwebkit2gtk-4.1.so", typeof(X11NativeWebView).Assembly, DllImportSearchPath.UserDirectories, out var webkitgtk41handle))
			{
				if (typeof(X11NativeWebView).Log().IsEnabled(LogLevel.Error))
				{
					typeof(X11NativeWebView).Log().Error($"libwebkit2gtk-4.1 was not found. Attempting to call {nameof(ProcessNavigation)} with an {nameof(HttpRequestMessage)} instance will crash the process.");
				}
			}
			else
			{
				Assembly assembly = Assembly.Load("WebKitGtkSharp");
				Type glibraryType = assembly.GetType("GLibrary") ?? throw new NullReferenceException("Couldn't find GLibrary in WebKitGtkSharp");
				Type libraryType = assembly.GetType("Library") ?? throw new NullReferenceException("Couldn't find Library in WebKitGtkSharp");
				object webkitLibraryEnum = Enum.ToObject(libraryType, 11);
				FieldInfo field = glibraryType.GetField("_libraries", BindingFlags.NonPublic | BindingFlags.Static) ?? throw new NullReferenceException("Couldn't find a field named _libraries in GLibrary");
				object libraries = field.GetValue(null) ?? throw new NullReferenceException("Couldn't read the static field named _libraries in GLibrary");
				var setItemMethod = libraries.GetType().GetMethod("set_Item") ?? throw new NullReferenceException("Couldn't find a method named set_Item in _libraries");
				setItemMethod.Invoke(libraries, [webkitLibraryEnum, webkitgtk41handle]);
				_usingWebKit2Gtk41 = true;
			}

			if (!WebKit.Global.IsSupported)
			{
				_initException = new PlatformNotSupportedException("libwebkit2gtk-4.0 is not found. Make sure that WebKit2GTK 4.0 and GTK 3 are installed. See https://aka.platform.uno/webview2 for more information");
				return;
			}

			GLib.ExceptionManager.UnhandledException += args =>
			{
				if (typeof(X11NativeWebView).Log().IsEnabled(LogLevel.Error))

View on GitHub (pinned to 0418340488)

Solutions

  1. Pin the WebKitGtkSharp package version that ships the GLibrary type that X11NativeWebView expects (check the referenced version in the Skia.X11 WebView add-in csproj).
  2. Ensure the correct libwebkit2gtk-4.1.so is installed so the patch path still resolves; if 4.1 is missing the code logs an error and proceeds to the 4.0 path instead (no throw here).
  3. If you maintain the add-in, update the reflection anchor (type/field/method names) to match the installed WebKitGtkSharp internals.
Defensive patterns

Strategy: validation

Validate before calling

// Validate the WebKitGtkSharp internals surface before relying on the patch
var asm = AppDomain.CurrentDomain.GetAssemblies().FirstOrDefault(a => a.GetName().Name == "WebKitGtkSharp");
bool gLibraryPresent = asm?.GetType("GLibrary") is not null;

Type guard

static bool WebKitGtkSharpHasGLibrary() => AppDomain.CurrentDomain.GetAssemblies().FirstOrDefault(a => a.GetName().Name == "WebKitGtkSharp")?.GetType("GLibrary") is not null;

Try / catch

try { NavigateWithHttpRequest(request); }
catch (NullReferenceException ex) when (ex.Message.Contains("GLibrary")) { /* fall back to URI navigation */ }

Prevention

When it happens

Trigger: A WebKitGtkSharp version is loaded whose public/internal structure no longer exposes a type literally named 'GLibrary' (the bootstrap class), while libwebkit2gtk-4.1.so IS present (the else-branch is taken).

Common situations: Updating the WebKitGtkSharp NuGet dependency on a distro; running on a Linux distribution whose packaged WebKitGtk# differs; trimming/IL-linking that strips the GLibrary type.

Related errors

AI-assisted analysis of unoplatform/uno@0418340488 (2026-08-13). Data as JSON: /api/errors/80c4103a77ea1155. Report an issue: GitHub.