Skip to main content
Version: Next Version 🚧

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:

videoTag.addEventListener("timeupdate", (event) => {
  if (event.target.duration - event.target.currentTime < 0.2) {
    let ended = new Event("ended");
    event.target.dispatchEvent(ended);
  }
});

Source: Lyimmi on the discussions board

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:

pacman -S gst-plugins-good

If the added package does not resolve the issue, additional GStreamer dependencies may be required. See the GStreamer installation page for more details.

Additional Notes​

Source: developomp on the Tauri discussion board.

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:

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...
}()
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