application.(*windowsSystemTray).positionWindow nil pointer dereference panic

[johnmaguire]

Description

We have seen the following stack trace a few times when opening our Wails program. We use a systray icon, attached to a systray menu, and sometimes change the systray icon depending on the application state.

runtime error: invalid memory address or nil pointer dereference
Stack trace:
runtime.panicmem
	at runtime/panic.go:262
runtime.sigpanic
	at runtime/signal_windows.go:401
github.com/wailsapp/wails/v3/pkg/w32.RectInRect
	at github.com/wailsapp/wails/v3@v3.0.0-alpha.10/pkg/w32/user32.go:817
github.com/wailsapp/wails/v3/pkg/application.(*windowsSystemTray).iconIsInTrayBounds
	at github.com/wailsapp/wails/v3@v3.0.0-alpha.10/pkg/application/systemtray_windows.go:145
github.com/wailsapp/wails/v3/pkg/application.(*windowsSystemTray).positionWindow
	at github.com/wailsapp/wails/v3@v3.0.0-alpha.10/pkg/application/systemtray_windows.go:67
github.com/wailsapp/wails/v3/pkg/application.(*SystemTray).PositionWindow.func1
	at github.com/wailsapp/wails/v3@v3.0.0-alpha.10/pkg/application/systemtray.go:129
github.com/wailsapp/wails/v3/pkg/application.InvokeSyncWithError.func1
	at github.com/wailsapp/wails/v3@v3.0.0-alpha.10/pkg/application/mainthread.go:51
github.com/wailsapp/wails/v3/pkg/application.(*windowsApp).invokeCallback
	at github.com/wailsapp/wails/v3@v3.0.0-alpha.10/pkg/application/mainthread_windows.go:125
github.com/wailsapp/wails/v3/pkg/application.(*windowsApp).wndProc
	at github.com/wailsapp/wails/v3@v3.0.0-alpha.10/pkg/application/application_windows.go:205
runtime.callbackWrap
	at runtime/syscall_windows.go:396
runtime.cgocallbackg1
	at runtime/cgocall.go:444
runtime.cgocallbackg
	at runtime/cgocall.go:350
runtime.cgocallback
	at runtime/asm_arm64.s:1131
runtime.systemstack_switch
	at runtime/asm_arm64.s:201
runtime.cgocall
	at runtime/cgocall.go:185
runtime.syscall_syscalln
	at runtime/syscall_windows.go:521
syscall.SyscallN
	at runtime/syscall_windows.go:500
syscall.(*Proc).Call
	at syscall/dll_windows.go:167
syscall.(*LazyProc).Call
	at syscall/dll_windows.go:287
github.com/wailsapp/wails/v3/pkg/w32.DispatchMessage
	at github.com/wailsapp/wails/v3@v3.0.0-alpha.10/pkg/w32/user32.go:463
github.com/wailsapp/wails/v3/pkg/application.(*windowsApp).runMainLoop
	at github.com/wailsapp/wails/v3@v3.0.0-alpha.10/pkg/application/mainthread_windows.go:64
github.com/wailsapp/wails/v3/pkg/application.(*windowsApp).run
	at github.com/wailsapp/wails/v3@v3.0.0-alpha.10/pkg/application/application_windows.go:163
github.com/wailsapp/wails/v3/pkg/application.(*App).Run
	at github.com/wailsapp/wails/v3@v3.0.0-alpha.10/pkg/application/application.go:591
main.main
	at github.com/DefinedNet/dnclient/cmd/dnclient-desktop/main.go:36
runtime.main
	at runtime/proc.go:283
runtime.goexit
	at runtime/asm_arm64.s:1223

To Reproduce

This has occurred once immediately after starting the app (though one of the first things the app does is check some system state and then update the system tray and menu accordingly.) In another case, this happened after a systray menu item was clicked, which should have triggered a window opening.

Expected behaviour

No panics.

Screenshots

No response

Attempted Fixes

No response

System Details

Wails (v3.0.0-alpha.10)  Wails Doctor

# System

┌──────────────────────────────────────────────────┐
| Name          | MacOS                            |
| Version       | 15.5                             |
| ID            | 24F74                            |
| Branding      | Sequoia                          |
| Platform      | darwin                           |
| Architecture  | arm64                            |
| Apple Silicon | true                             |
| CPU           | Apple M4 Max                     |
| CPU 1         | Apple M4 Max                     |
| CPU 2         | Apple M4 Max                     |
| GPU           | 40 cores, Metal Support: Metal 3 |
| Memory        | 128 GB                           |
└──────────────────────────────────────────────────┘

# Build Environment

┌────────────────────────────────┐
| Wails CLI    | v3.0.0-alpha.10 |
| Go Version   | go1.24.4        |
| -buildmode   | exe             |
| -compiler    | gc              |
| CGO_CFLAGS   |                 |
| CGO_CPPFLAGS |                 |
| CGO_CXXFLAGS |                 |
| CGO_ENABLED  | 1               |
| CGO_LDFLAGS  |                 |
| GOARCH       | arm64           |
| GOARM64      | v8.0            |
| GOOS         | darwin          |
└────────────────────────────────┘

# Dependencies

┌────────────────────────────────────────────────────────────────────────┐
| Xcode cli tools | 2409                                                 |
| npm             | 10.9.2                                               |
| *NSIS           | Not Installed. Install with `brew install makensis`. |
|                                                                        |
└─────────────────────── * - Optional Dependency ────────────────────────┘

# Checking for issues

 SUCCESS  No issues found

# Diagnosis

 SUCCESS  Your system is ready for Wails development!

Need documentation? Run: wails3 docs
 ♥   If Wails is useful to you or your company, please consider sponsoring the project: wails3 sponsor

Additional context

We are running a slight fork of v3.0.0-alpha.10 with a few commits pulled in from the mega-menu-fixes branch to fix other panics we saw more frequently: v3.0.0-alpha.10...DefinedNet:wails:windows-fixes

That being said, the panic does not appear directly related to the code in any of these commits.

[dosubot]

This panic is likely caused by a race condition or premature access to uninitialized system tray resources—specifically, one of the RECT pointers or structs passed to RectInRect is nil, often due to Windows API calls failing or returning zero values before the tray or window is fully initialized. The code in v3.0.0-alpha.10 doesn't always check for nil/zero values before dereferencing, especially around Windows API calls in positionWindow and iconIsInTrayBounds.

This kind of issue has been seen with other Wails services (like notifications) on Windows and Linux, where calling service methods before the platform-specific Startup logic completes can result in nil pointer panics. Wails doesn't enforce initialization order, so it's up to the developer to ensure system tray operations only happen after startup—ideally from within an OnStartup handler or after app.Run() has completed. See the discussion on initialization requirements for more details: source.

There was also a related bug with system tray icon resource management (not destroying previous icon handles when changing icons), which was fixed in commit a8c8417. If your fork doesn't include this commit, it's worth pulling it in, as it addresses resource issues when changing icons rapidly: source.

To mitigate the panic, ensure all system tray operations (including icon/menu updates) are deferred until after the app is fully initialized, and consider adding explicit nil checks around Windows API calls that return pointers or structs used in positionWindow and iconIsInTrayBounds. This should help avoid dereferencing nil values if initialization hasn't completed or if a system call fails.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[johnmaguire]

Wails doesn't enforce initialization order, so it's up to the developer to ensure system tray operations only happen after startup—ideally from within an OnStartup handler or after app.Run() has completed. See the discussion on initialization requirements for more details: #4449.

We do take a number of actions before Run() is called, but this is deterministically true, so I'm not sure why we would be seeing this randomly. Notably, we call app.RegisterService(), app.SystemTray.New() (and call SetMenu, SetTooltip and various set icon methods on it). We also call app.window.NewWithOptions() and register hooks against them. Everything else waits until events.Common.ApplicationStarted (e.g. actually showing windows.)

And as mentioned in the original issue, we have seen this panic after the app is already in a steady-state. I do not think this is an order of operations error on our end.

Commit a8c8417 is already in v3.0.0-alpha.10, so we do have that commit.

[leaanthony]

@johnmaguire - Please try the above PR to see if this fixes your problem. Let us know how you get on 👍

[johnmaguire]

Thanks for the fast response @leaanthony! I will let you know if we see any further crashes in this area of code, or any new negative effects.

P.S. I think the PR title has a small mistake (Linux -> Windows.)

🙌

[leaanthony]

Merged. Can reopen if there's an issue.