What causes "Create image list failed" in wailsapp/wails?

Validate arguments before calling: cx > 0, cy > 0, flags limited to ILC_* constants (e.g. ILC_COLOR32), and modest cInitial/cGrow

wailsapp/wails · error

Create image list failed

Error message

Create image list failed

What it means

ImageList_Create is a thin wrapper over the Win32 comctl32 ImageList_Create API in Wails' internal w32 package; it panics when the native call returns NULL, meaning image-list creation failed entirely. In the current v3 tree it has no callers (it was inherited from v2's winc layer, where it backs toolbar/imagelist helpers), so in practice only code that imports and calls v3/pkg/w32 directly can hit it.

Source

Thrown at v3/pkg/w32/comctl32.go:45

)

func InitCommonControlsEx(lpInitCtrls *INITCOMMONCONTROLSEX) bool {
	ret, _, _ := procInitCommonControlsEx.Call(
		uintptr(unsafe.Pointer(lpInitCtrls)))

	return ret != 0
}

func ImageList_Create(cx, cy int, flags uint, cInitial, cGrow int) HIMAGELIST {
	ret, _, _ := procImageList_Create.Call(
		uintptr(cx),
		uintptr(cy),
		uintptr(flags),
		uintptr(cInitial),
		uintptr(cGrow))

	if ret == 0 {
		panic("Create image list failed")
	}

	return HIMAGELIST(ret)
}

func ImageList_Destroy(himl HIMAGELIST) bool {
	ret, _, _ := procImageList_Destroy.Call(
		uintptr(himl))

	return ret != 0
}

func ImageList_GetImageCount(himl HIMAGELIST) int {
	ret, _, _ := procImageList_GetImageCount.Call(
		uintptr(himl))

	return int(ret)
}

View on GitHub (pinned to 0e754b1b40)

Solutions

Validate arguments before calling: cx > 0, cy > 0, flags limited to ILC_* constants (e.g. ILC_COLOR32), and modest cInitial/cGrow
If you control the call site, check the returned handle instead of using this wrapper, or copy the wrapper and return an error rather than panicking
In restricted sessions (services/RDP disconnected), initialize common controls (InitCommonControlsEx) first and ensure a desktop heap is available

Example fix

// before
himl := w32.ImageList_Create(0, 16, w32.ILC_COLOR32, 4, 4) // cx=0 -> native NULL -> panic

// after
himl := w32.ImageList_Create(16, 16, w32.ILC_COLOR32, 4, 4) // valid size

Defensive patterns

Strategy: validation

Validate before calling

func createImageList(cx, cy, cInitial, cGrow int, flags uint) (w32.HIMAGELIST, bool) {
	if cx <= 0 || cy <= 0 || cInitial < 0 || cGrow < 0 {
		return 0, false
	}
	return w32.ImageList_Create(cx, cy, flags, cInitial, cGrow), true
}

Try / catch

defer func() {
	if r := recover(); r != nil {
		log.Printf("ImageList_Create failed: %v", r)
	}
}()
himl := w32.ImageList_Create(16, 16, w32.ILC_COLOR32, 4, 4)

Prevention

Always pass positive cx/cy and ILC_* flags from the w32 package
Verify common controls are initialized in the process before creating image lists
Avoid calling internal w32 helpers from service/headless sessions without a desktop

When it happens

Trigger: Calling w32.ImageList_Create with invalid arguments: cx or cy <= 0, an unknown flags combination, or cInitial/cGrow values that overflow on 32-bit; or legitimately failing at the OS level (out of memory, comctl32 not available in the session, e.g. some server/service contexts).

Common situations: Custom Win32 integration code reusing Wails' w32 helpers; headless/service sessions lacking a common-controls-capable desktop; porting v2 winc-based drawing code into v3.

Related errors

AI-assisted analysis of wailsapp/wails@0e754b1b40 (2026-08-15). Data as JSON: /api/errors/e5911743f3a513a9. Report an issue: GitHub.