Common problems
Most of what goes wrong in a package has gone wrong before. These pages collect the problems FlatPark packages have hit, each with how to recognise it, why it happens, and the fix that worked, with a package that does it.
Start from the symptom:
- Desktop integration: windows not grouped, no media controls, no tray icon, a second instance, file associations.
- Rendering and fonts: blank or transparent windows, crashes when switching views, tiny UI, boxes instead of characters.
- Clipboard, secrets and system services: copy and paste, saved passwords, keyrings, screen capture, accessibility.
- Nested sandboxes and updaters: an app’s own sandbox, an in-app updater, apps that manage the host.
- By stack: a checklist for Electron, Chromium browsers, Tauri, Wails, GPUI, Slint, Flutter, Qt, .NET, Java and Wine apps.
Two rules apply to every fix here:
- Fix from the outside. Wrapper variables and flags,
finish-args, extra downloads and prebuilt stacks are fine for any app. Injecting code or changing the vendor’s files is never done to an open-source app, and only as a last, declared resort for a closed-source one (permissions). - Stop when workarounds pile up. One workaround is normal; a second or third for the same app means stop and ask whether it should be listed at all.
For agents
Diagnosing
- Run it in the sandbox, not on the host.
flatpak run --command=sh <app-id>gives a shell with the app’s exact sandbox;flatpak enter <app-id> shjoins a running one. - D-Bus problems are silent.
flatpak run --log-session-bus <app-id>prints every call the bus proxy filters (Filtering message due to arg0, failedRequestName). Missing tray icons, media controls and second instances almost always show up here. - Read the binary before guessing.
stringsfinds environment variables the app reads (SLINT_*,<APP>_UI_FONT,WEBKIT_*), D-Bus names it owns (org.SingleInstance.DBus), and the toolkit version. Rust apps built withtracingtake--env=RUST_LOG=<crate>=debug. - Measure, don’t derive. Window classes, bus names and file paths differ from what the vendor’s desktop file or docs say often enough that every value written into a package is checked on the running app.
- Compare with a real control. To prove a setting is unnecessary, build without it; don’t point the app at a different value, which can take another path entirely.
- Check global overrides first when a test shows a permission the package
doesn’t grant:
cat ~/.local/share/flatpak/overrides/global. - Test on a private display. A rootful
Xwayland :99accepts XTEST input and screenshots; run the app with the host’sDISPLAY=:99(not--env=DISPLAY), and stop the display when done.
- Desktop integrationWindows not grouped, media controls missing, no tray icon, a second instance starting, file associations.
- Rendering and fontsBlank or see-through windows, web views that crash, an interface that is too small, and boxes instead of characters.
- Clipboard, secrets and system servicesCopy and paste, saved passwords and keyrings, screen capture, accessibility, and host commands.
- Nested sandboxes and updatersApps with their own sandbox, in-app updaters, and apps built to manage the host.
- By stackA checklist per stack (Electron, Chromium browsers, Tauri, Wails, GPUI, Slint, Flutter, Qt, .NET, Java, Wine) of what to set and what to test.