What causes "keyState slice must have a size of 256 bytes" in wailsapp/wails?

Allocate exactly 256 bytes: keyState := make([]byte, 256)

keyState slice must have a size of 256 bytes

Error message

keyState slice must have a size of 256 bytes

What it means

GetKeyboardState panics unless the caller passes a []byte of exactly length 256, because the underlying Win32 API fills a fixed 256-entry key-state array indexed by virtual-key code. This is a defensive precondition check inside the wrapper, not a system failure.

Source

Thrown at v3/pkg/w32/user32.go:1267

	return ret != 0
}

func BeginPaint(hwnd HWND, paint *PAINTSTRUCT) HDC {
	ret, _, _ := procBeginPaint.Call(
		uintptr(hwnd),
		uintptr(unsafe.Pointer(paint)))
	return HDC(ret)
}

func EndPaint(hwnd HWND, paint *PAINTSTRUCT) {
	procEndPaint.Call(
		uintptr(hwnd),
		uintptr(unsafe.Pointer(paint)))
}

func GetKeyboardState(keyState []byte) bool {
	if len(keyState) != 256 {
		panic("keyState slice must have a size of 256 bytes")
	}
	ret, _, _ := procGetKeyboardState.Call(uintptr(unsafe.Pointer(&keyState[0])))
	return ret != 0
}

func MapVirtualKeyEx(uCode, uMapType uint, dwhkl HKL) uint {
	ret, _, _ := procMapVirtualKeyEx.Call(
		uintptr(uCode),
		uintptr(uMapType),
		uintptr(dwhkl))
	return uint(ret)
}

func MapVirtualKey(uCode uint, uMapType uint) uint {
	ret, _, _ := procMapVirtualKey.Call(uintptr(uCode), uintptr(uMapType))
	return uint(ret)
}

View on GitHub (pinned to 0e754b1b40)

Solutions

Allocate exactly 256 bytes: keyState := make([]byte, 256)
Reuse a single package-level [256]byte array across calls instead of reallocating
Add a compile-time-visible constant or helper so callers cannot guess wrong

Example fix

// before
keys := make([]byte, 128) // wrong size
w32.GetKeyboardState(keys)

// after
keys := make([]byte, 256) // VK array is 256 entries
w32.GetKeyboardState(keys)

Defensive patterns

Strategy: type-guard

Validate before calling

if len(keyState) != 256 {
    return false, fmt.Errorf("need 256 bytes, got %d", len(keyState))
}
return w32.GetKeyboardState(keyState), nil

Type guard

func isValidKeyStateBuffer(b []byte) bool { return len(b) == 256 }

Prevention

Standardize on make([]byte, 256) or a [256]byte array in every caller
Wrap the API once in your own helper that allocates correctly

When it happens

Trigger: Calling w32.GetKeyboardState(keyState) where keyState was allocated with make([]byte, 128), with a dynamic size, or as an empty slice; reusing a struct-embedded slice that was truncated.

Common situations: Keyboard-accelerator or shortcut handling code copied from samples that pass arbitrary buffers; passing a pointer into a larger struct cast to a short slice.

Related errors

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