{"record":{"id":"f1daa541ee8f3d85","repo":"dotnet/maui","slug":"unable-to-initialize-gdi","errorCode":null,"errorMessage":"Unable to initialize GDI+","messagePattern":"Unable to initialize GDI\\+","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"critical","filePath":"src/Compatibility/Core/src/WPF/Microsoft.Windows.Shell/Standard/NativeMethods.cs","lineNumber":1614,"sourceCode":"\t\tprotected override bool ReleaseHandle()\n\t\t{\n\t\t\tStatus s = NativeMethods.GdiplusShutdown(this.handle);\n\t\t\treturn s == Status.Ok;\n\t\t}\n\n\t\t[SuppressMessage(\"Microsoft.Performance\", \"CA1811:AvoidUncalledPrivateCode\")]\n\t\t[SuppressMessage(\"Microsoft.Usage\", \"CA2201:DoNotRaiseReservedExceptionTypes\")]\n\t\tpublic static SafeGdiplusStartupToken Startup()\n\t\t{\n\t\t\tIntPtr unsafeHandle;\n\t\t\tStartupOutput output;\n\t\t\tStatus s = NativeMethods.GdiplusStartup(out unsafeHandle, new StartupInput(), out output);\n\t\t\tif (s == Status.Ok)\n\t\t\t{\n\t\t\t\tSafeGdiplusStartupToken safeHandle = new SafeGdiplusStartupToken(unsafeHandle);\n\t\t\t\treturn safeHandle;\n\t\t\t}\n\t\t\tthrow new Exception(\"Unable to initialize GDI+\");\n\t\t}\n\t}\n\n\tinternal sealed class SafeConnectionPointCookie : SafeHandleZeroOrMinusOneIsInvalid\n\t{\n\t\tIConnectionPoint _cp;\n\t\t// handle holds the cookie value.\n\n\t\t[SuppressMessage(\"Microsoft.Performance\", \"CA1811:AvoidUncalledPrivateCode\")]\n\t\t[SuppressMessage(\"Microsoft.Naming\", \"CA2204:Literals should be spelled correctly\", MessageId = \"IConnectionPoint\")]\n\t\tpublic SafeConnectionPointCookie(IConnectionPointContainer target, object sink, Guid eventId)\n\t\t\t: base(true)\n\t\t{\n\t\t\tVerify.IsNotNull(target, \"target\");\n\t\t\tVerify.IsNotNull(sink, \"sink\");\n\t\t\tVerify.IsNotDefault(eventId, \"eventId\");\n\n\t\t\thandle = IntPtr.Zero;","sourceCodeStart":1596,"sourceCodeEnd":1632,"githubUrl":"https://github.com/dotnet/maui/blob/f377ff1c5ee04d334d8a925f50c83a6b7afddf03/src/Compatibility/Core/src/WPF/Microsoft.Windows.Shell/Standard/NativeMethods.cs#L1596-L1632","documentation":"NativeMethods.Startup throws Exception(\"Unable to initialize GDI+\") when GdiplusStartup returns a Status other than Ok. GDI+ must be initialised exactly once per process before any GDI+ rendering API is used; a non-Ok status means the runtime could not load or initialise GDI+ (gdiplus.dll).","triggerScenarios":"GdiplusStartup fails due to missing/corrupt gdiplus.dll; out of memory or GDI+ object exhaustion; calling Startup concurrently without the SafeHandle guard; locked-down environment preventing native DLL load.","commonSituations":"Stripped Windows image lacking gdiplus.dll; sandboxed/app-container environment; corrupted system files; running on a non-Windows platform where the shell assembly is force-loaded.","solutions":["Ensure gdiplus.dll is present and loadable (run sfc /scannow to repair system files).","Confirm the process runs on a supported Windows desktop session.","Avoid calling Startup concurrently; let the SafeGdiplusStartupToken singleton manage it.","Free GDI+ resources (images, graphics) promptly to avoid exhaustion that can cause Startup to fail."],"exampleFix":"// before\nvar token = NativeMethods.Startup(); // throws if gdiplus.dll missing\n\n// after\nif (!System.IO.File.Exists(System.IO.Path.Combine(Environment.SystemDirectory, \"gdiplus.dll\")))\n    throw new InvalidOperationException(\"gdiplus.dll not available\");\nvar token = NativeMethods.Startup();","handlingStrategy":"validation","validationCode":"if (!System.IO.File.Exists(System.IO.Path.Combine(Environment.SystemDirectory, \"gdiplus.dll\")))\n    throw new InvalidOperationException(\"gdiplus.dll not available\");\nvar token = NativeMethods.Startup();","typeGuard":"static bool GdiplusAvailable =>\n    System.IO.File.Exists(System.IO.Path.Combine(Environment.SystemDirectory, \"gdiplus.dll\"));","tryCatchPattern":"try { var token = NativeMethods.Startup(); }\ncatch (Exception ex) when (ex.Message.Contains(\"GDI+\"))\n{ /* repair system files or run on supported Windows; cannot recover at runtime */ }","preventionTips":["Ensure gdiplus.dll is present (run sfc /scannow if missing).","Run on a supported Windows desktop session.","Release GDI+ resources promptly to keep Startup succeeding."],"tags":["wpf","gdi","gdiplus","native-interop","startup"],"backgroundTag":null,"analyzedSha":"f377ff1c5ee04d334d8a925f50c83a6b7afddf03","analyzedAt":"2026-08-13T14:26:18.069Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}