Skip to content

Fix Linux startup crash caused by the update notification dialog#2791

Open
tadeasf wants to merge 2 commits into
pyfa-org:masterfrom
tadeasf:fix/linux-update-dialog-webview-crash
Open

Fix Linux startup crash caused by the update notification dialog#2791
tadeasf wants to merge 2 commits into
pyfa-org:masterfrom
tadeasf:fix/linux-update-dialog-webview-crash

Conversation

@tadeasf

@tadeasf tadeasf commented Jul 26, 2026

Copy link
Copy Markdown

Hi! I love pyfa - I've been using it for years. I'm primarily on Linux these days, and it would crash on startup, so I decided to fix that and give some love back to the project. More to follow if you're happy with my work (I was thinking about the dark mode request, but then again, on Linux it's already sort of there, so I'd need to switch machines... eh, we'll see).

What / why

Addresses #2740 - the Linux AppImage dies ~2-3 s after launch with nothing in the Python log.

Root cause

The update notification dialog (gui/updateDialog.py) is the only user of wx.html2.WebView. On wxGTK that's WebKitGTK, and:

  1. AppImage: the builder bundles jammy's libwebkit2gtk-4.0-37. The library loads, but WebKit then tries to spawn its helper processes at the Ubuntu-hardcoded path /usr/lib/x86_64-linux-gnu/webkit2gtk-4.0/WebKitNetworkProcess, which doesn't exist on other distros - a fatal GLib error that aborts the app with no Python traceback. This is why it "appeared" with 2.66.2: git diff v2.66.1..v2.66.3 touched nothing in the startup/update path - 2.66.2 was simply the first release new enough for the popup to run at all. Reproduced on Fedora 44 with the v2.64.2 AppImage (exit 133 = SIGTRAP):

    ** (pyfa.py:856537): ERROR **: 20:41:04.016: Unable to spawn a new child process:
    Failed to spawn child process "/usr/lib/x86_64-linux-gnu/webkit2gtk-4.0/WebKitNetworkProcess"
    (No such file or directory)
    

    In ~/.pyfa/pyfa.log, every crashed launch ends exactly at service.update: Starting Check Update Thread.

  2. From source on distros without webkit2gtk-4.0 (Fedora today): import wx.html2 itself fails, so startup dies before the main window - gui/mainFrame.py imports the dialog at module level.

Changes

  • gui/updateDialog.py: never use the WebView on wxGTK (a native abort can't be caught with try/except) - release notes render in a read-only wx.TextCtrl instead; the Download button already opens the release page in a browser. Other platforms keep the WebView but check IsBackendAvailable() and guard WebView.New()/SetPage(), falling back to plain text on failure. import wx.html2 is now lazy so startup doesn't depend on WebKitGTK being present. Two small guards while there: releaseInfo['body'] may be None (would TypeError), and the dialog title contained a literal {} - it now shows the release tag.
  • gui/mainFrame.py: ShowUpdateBox wrapped in try/except + logging so a dialog failure can never silently break startup again.
  • dist_assets/linux/AppImageBuilder.yml: drop libwebkit2gtk-4.0-37 - nothing loads it on Linux anymore. Happy to split this into a separate PR if preferred.

Behavior on Windows/macOS is unchanged (WebView2/WKWebView still used, now guarded).

Verified

  • Reproduced pre-fix: AppImage crash (signature above), and from-source startup failure at import wx.html2, both on Fedora 44.
  • Post-fix: app starts and stays up from source (venv, wxPython 4.2.1 gtk3 wheels); faked an old version in version.yml to force the popup - app survives, dialog opens with plain-text notes; headless UpdateDialog construction against live release data passes; flake8 (tox pep8 flags) adds zero findings on changed files.
  • Not verified: a rebuilt AppImage (needs appimage-builder on Ubuntu) - but the WebKitGTK code path is gone entirely on Linux.

Notes

Flagging so that you know: service/update.py swallows the primary endpoint's error silently (lines 54-59) and assumes the response is a JSON list (line 61) - might be worth fixing later?

tadeasf added 2 commits July 26, 2026 21:51
On Linux (wxGTK), wx.html2.WebView is backed by WebKitGTK. In the AppImage the bundled Ubuntu build of WebKitGTK fails to spawn its helper processes on other distributions, which aborts the whole application a few seconds after startup (issue pyfa-org#2740). On distributions without webkit2gtk-4.0, even importing wx.html2 fails, which breaks startup from source as well.

Never use the WebView on wxGTK and fall back to a plain text release notes widget there. On other platforms guard the WebView creation and fall back to plain text when no backend is available. Also guard ShowUpdateBox so a dialog failure can no longer take down startup, default empty release notes bodies to an empty string and put the release tag in the dialog title instead of a literal '{}'.

Behavior on Windows and macOS is unchanged.
The update dialog no longer uses wx.html2.WebView on Linux, so nothing in the AppImage loads libwebkit2gtk-4.0-37 anymore and it can be dropped from the bundle.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant