{"record":{"id":"8a570ed0a4f2a097","repo":"wailsapp/wails","slug":"failed-to-load-user32-dll-v","errorCode":null,"errorMessage":"failed to load user32.dll: %v","messagePattern":"failed to load user32\\.dll: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"v2/internal/frontend/desktop/windows/winc/icon.go","lineNumber":37,"sourceCode":"\t\"github.com/wailsapp/wails/v2/internal/frontend/desktop/windows/winc/w32\"\n)\n\nvar (\n\tuser32                 = syscall.NewLazyDLL(\"user32.dll\")\n\tgdi32                  = syscall.NewLazyDLL(\"gdi32.dll\")\n\tprocGetIconInfo        = user32.NewProc(\"GetIconInfo\")\n\tprocDeleteObject       = gdi32.NewProc(\"DeleteObject\")\n\tprocGetObject          = gdi32.NewProc(\"GetObjectW\")\n\tprocGetDIBits          = gdi32.NewProc(\"GetDIBits\")\n\tprocCreateCompatibleDC = gdi32.NewProc(\"CreateCompatibleDC\")\n\tprocSelectObject       = gdi32.NewProc(\"SelectObject\")\n\tprocDeleteDC           = gdi32.NewProc(\"DeleteDC\")\n)\n\nfunc init() {\n\t// Validate DLL loads at initialization time to surface missing APIs early\n\tif err := user32.Load(); err != nil {\n\t\tpanic(fmt.Sprintf(\"failed to load user32.dll: %v\", err))\n\t}\n\tif err := gdi32.Load(); err != nil {\n\t\tpanic(fmt.Sprintf(\"failed to load gdi32.dll: %v\", err))\n\t}\n}\n\n// ICONINFO mirrors the Win32 ICONINFO struct\ntype ICONINFO struct {\n\tFIcon    int32\n\tXHotspot uint32\n\tYHotspot uint32\n\tHbmMask  uintptr\n\tHbmColor uintptr\n}\n\n// http://msdn.microsoft.com/en-us/library/windows/desktop/dd183376.aspx\ntype BITMAPINFOHEADER struct {\n\tBiSize          uint32","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/wailsapp/wails/blob/0e754b1b40ba9044c2a1460e23b7c3de20fc5cf3/v2/internal/frontend/desktop/windows/winc/icon.go#L19-L55","documentation":"icon.go's package init eagerly calls user32.Load() and panics with the wrapped error if user32.dll cannot be loaded, surfacing missing system APIs before any icon function runs. user32.dll is a permanent Windows system DLL, so failure means the process environment itself is broken: the DLL is blocked by policy/security software, the image is being loaded in an unusual host (server core without interactive session machinery, wine/containers missing it), or API sets are unresolved in exotic loader contexts.","triggerScenarios":"Importing the winc icon package on a Windows SKU where user32 is unavailable/blocked (locked-down server core, sandbox); antivirus/EDR blocking DLL load; running under an emulation layer missing user32; corruption of the system DLL search path (SAFESEARCH mode with a rogue user32.dll nearby).","commonSituations":"CI or container images attempting to run/test a GUI build headless; hardened kiosk/terminal servers; a fake user32.dll shadowing the real one in the app directory.","solutions":["Run the GUI build only on desktop Windows SKUs with an interactive session; for headless CI, gate tests that import winc with build tags or skip on non-interactive sessions","Check the wrapped error text (%v) — ERROR_ACCESS_DENIED points to AV/EDR policy, ERROR_MOD_NOT_FOUND points to a missing/blocked system DLL","Remove any user32.dll shadow copies from the application directory and verify C:\\Windows\\System32\\user32.dll exists and loads (rundll32 sanity check)","If running under Wine/Proton, ensure a 64-bit windows user32 is present for a 64-bit build"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// init() runs on import; you cannot catch it in-process. Pre-flight the host instead:\n// (run in a launcher script or a tiny bootstrap exe before the GUI binary)\n//   if not exist %WINDIR%\\System32\\user32.dll exit /b 1","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Deploy GUI builds only on desktop Windows with an interactive session","Keep winc imports behind a 'gui' build tag so headless builds never trigger init","Check the wrapped error for access-denied (policy) vs module-not-found (missing DLL)"],"tags":["windows","dll","init-time","environment","winc","panic"],"backgroundTag":null,"analyzedSha":"0e754b1b40ba9044c2a1460e23b7c3de20fc5cf3","analyzedAt":"2026-08-15T14:17:36.034Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}