mirror of
https://github.com/wailsapp/wails.git
synced 2026-03-14 14:45:49 +01:00
01b661f6a5* feat(v2): add runtime.ResetSignalHandlers() for Linux panic recovery
Add a new runtime function that allows users to reset signal handlers
before code that might panic from nil pointer dereferences.
On Linux, WebKit installs signal handlers without the SA_ONSTACK flag,
which prevents Go from properly recovering from panics caused by
SIGSEGV and other signals. This function adds SA_ONSTACK to the
relevant signal handlers (SIGSEGV, SIGBUS, SIGFPE, SIGABRT).
Usage:
```go
go func() {
defer func() {
if err := recover(); err != nil {
log.Printf("Recovered: %v", err)
}
}()
runtime.ResetSignalHandlers()
// Code that might panic...
}()
```
The function is a no-op on macOS and Windows.
Fixes #3965
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
* test(v2): add panic-recovery-test example
Add an example that demonstrates the Linux signal handler issue (#3965)
and verifies the fix using runtime.ResetSignalHandlers().
The example includes:
- A Greet function that triggers a nil pointer dereference after a delay
- Auto-call from frontend after 5 seconds
- README with reproduction steps
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
126 lines
4.1 KiB
Text
126 lines
4.1 KiB
Text
# Linux
|
|
|
|
This page has miscellaneous guides related to developing Wails applications for Linux.
|
|
|
|
## Video tag doesn't fire "ended" event
|
|
|
|
When using a video tag, the "ended" event is not fired when the video is finished playing. This is a bug
|
|
in WebkitGTK, however you can use the following workaround to fix it:
|
|
|
|
```js
|
|
videoTag.addEventListener("timeupdate", (event) => {
|
|
if (event.target.duration - event.target.currentTime < 0.2) {
|
|
let ended = new Event("ended");
|
|
event.target.dispatchEvent(ended);
|
|
}
|
|
});
|
|
```
|
|
|
|
Source: [Lyimmi](https://github.com/Lyimmi) on the
|
|
[discussions board](https://github.com/wailsapp/wails/issues/1729#issuecomment-1212291275)
|
|
|
|
## GStreamer error when using Audio or Video elements
|
|
|
|
If you are seeing the following error when including `<Audio>` or `<Video>` elements on Linux, you may need to install `gst-plugins-good`.
|
|
|
|
```
|
|
GStreamer element autoaudiosink not found. Please install it
|
|
```
|
|
|
|
### Installing
|
|
|
|
Run the following distro relevant install command:
|
|
|
|
```mdx-code-block
|
|
import Tabs from "@theme/Tabs";
|
|
import TabItem from "@theme/TabItem";
|
|
|
|
<Tabs
|
|
defaultValue="Arch"
|
|
values={[
|
|
{ label: "Arch", value: "Arch" },
|
|
{ label: "Debian/Ubuntu", value: "Debian" },
|
|
{ label: "Fedora", value: "Fedora" },
|
|
]}
|
|
>
|
|
<TabItem value="Arch">
|
|
|
|
pacman -S gst-plugins-good
|
|
|
|
</TabItem>
|
|
<TabItem value="Debian">
|
|
|
|
apt-get install gstreamer1.0-plugins-good
|
|
|
|
</TabItem>
|
|
<TabItem value="Fedora">
|
|
|
|
dnf install gstreamer1-plugins-good
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
```
|
|
|
|
If the added package does not resolve the issue, additional GStreamer dependencies may be required. [See the GStreamer installation page for more details.](https://gstreamer.freedesktop.org/documentation/installing/on-linux.html)
|
|
|
|
### Additional Notes
|
|
|
|
- This issue is caused by [an upstream issue with WebkitGTK](https://bugs.webkit.org/show_bug.cgi?id=146351).
|
|
- [Arch based systems](https://wiki.archlinux.org/title/Arch-based_distributions) seem to have this issue more often than other distributions.
|
|
- This issue impacts [Tauri apps](https://tauri.app/).
|
|
|
|
Source: [developomp](https://github.com/developomp) on the [Tauri discussion board](https://github.com/tauri-apps/tauri/issues/4642#issuecomment-1643229562).
|
|
|
|
## Panic Recovery / Signal Handling Issues
|
|
|
|
### App crashes with "non-Go code set up signal handler without SA_ONSTACK flag"
|
|
|
|
On Linux, if your application crashes with an error like:
|
|
|
|
```
|
|
signal 11 received but handler not on signal stack
|
|
fatal error: non-Go code set up signal handler without SA_ONSTACK flag
|
|
```
|
|
|
|
This occurs because WebKit (used for the webview) installs signal handlers that interfere with Go's panic recovery mechanism.
|
|
Normally, Go can convert signals like SIGSEGV (from nil pointer dereferences) into recoverable panics, but WebKit's signal
|
|
handlers prevent this.
|
|
|
|
### Solution
|
|
|
|
Use the `runtime.ResetSignalHandlers()` function immediately before code that might panic:
|
|
|
|
```go
|
|
import "github.com/wailsapp/wails/v2/pkg/runtime"
|
|
|
|
go func() {
|
|
defer func() {
|
|
if err := recover(); err != nil {
|
|
log.Printf("Recovered from panic: %v", err)
|
|
}
|
|
}()
|
|
// Reset signal handlers right before potentially dangerous code
|
|
runtime.ResetSignalHandlers()
|
|
|
|
// Your code that might panic...
|
|
}()
|
|
```
|
|
|
|
:::warning Important
|
|
|
|
- Call `ResetSignalHandlers()` in each goroutine where you need panic recovery
|
|
- Call it immediately before the code that might panic, as WebKit may reset the handlers at any time
|
|
- This is only necessary on Linux - the function is a no-op on other platforms
|
|
|
|
:::
|
|
|
|
### Why This Happens
|
|
|
|
WebKit installs its own signal handlers for garbage collection and other internal processes. These handlers don't include
|
|
the `SA_ONSTACK` flag that Go requires to properly handle signals on the correct stack. When a signal like SIGSEGV occurs,
|
|
Go's runtime can't recover because the signal is being handled on the wrong stack.
|
|
|
|
The `ResetSignalHandlers()` function adds the `SA_ONSTACK` flag to the signal handlers for SIGSEGV, SIGBUS, SIGFPE, and
|
|
SIGABRT, allowing Go's panic recovery to work correctly.
|
|
|
|
Source: [GitHub Issue #3965](https://github.com/wailsapp/wails/issues/3965)
|