K2 DEPLOYMENT — STARTUP OF THE LINUX APPIMAGE ON ANY DESKTOP

Context

The published K2 Qt6 Linux AppImage (Katalog-linux_qt6_v2.13.beta1-x86_64.AppImage) crashes at startup on a desktop that is not a KDE session. The maintainer reproduced it on Linux Mint / Cinnamon in a VirtualBox virtual machine:

• A plain run prints only the two kf.i18n: KLocalizedString: Domain is not set... lines and dies. It never reaches the application's own first output (WARNING: Unknown SearchIn value, using default: "" and the three lines that follow it).
• The same AppImage run as QT_QPA_PLATFORMTHEME=generic ./Katalog-...AppImage starts fully, prints those four application lines, and displays the K2 user interface.
• A QT_DEBUG_PLUGINS=1 run dies at the same point, after Qt has scanned the styles and accessible plugin directories and loaded nothing from styles.

So the failure is in platform-theme and style initialisation, before the application's own settings are loaded — no K2 code has run yet — and naming a platform theme that is present in the bundle avoids it.

A mitigation for this exact failure had already been attempted, and that is the trap. Before the fix, both K2 Qt6 AppImage workflows carried a byte-identical AppRun that only unset the variable on a non-KDE session, under a comment claiming it fixes "SIGSEGV on non-KDE desktops (Cinnamon, GNOME, etc.)". Unsetting the variable does not stop Qt from auto-selecting a platform theme from the session: on a GTK desktop such as Cinnamon or XFCE Qt selects gtk3 on its own and loads the bundled plugin against the host's GTK stack. Neither workflow removes that plugin from the bundle. That mitigation was therefore incomplete, not absent — which is why the defect read as new while the code looked as though it were already handled. Anyone re-reading that comment would have concluded the case was closed; K2D-C3 exists so the comment can no longer say so.

One thing this page does not claim, because it is not established: which bundled plugin fails. The evidence above locates the failure in theme and style initialisation and proves that forcing generic avoids it. It does not name the plugin. The authorised fix does not depend on that answer (see K2D-C5).

This is not a 2.13 regression

The released 2.12 AppImage was then run on the same Linux Mint / Cinnamon virtual machine and crashes there too. So the defect has been shipping in a released version: it affects real users on GTK desktops — Cinnamon, XFCE, GNOME — and not only beta testers.

Confirmed affected on Mint / Cinnamon: 2.12 (released) and 2.13.beta1. No other released version was tested, so the claim is not extended back to 2.11 or earlier — untested, not known good.

Because the fix is packaging-only (K2D-C1), a corrected AppImage for an already-released version needs no code change and no new application release — only a rebuild with the patched AppRun. Whether to actually republish 2.12 that way is the maintainer's release decision; it is an available option, not planned work, and nothing on this page authorises it.

This page covers whether the packaged K2 build starts. It does not cover what K2 does once it is running, and it authorises no change to the K2 user interface: K2 is in maintenance mode, and the fix is in the launcher only.

Reading the requirement IDs. Each requirement has a permanent ID. IDs are never renumbered or reused; a retired requirement is marked [Removed], not deleted. Status is one of [Implemented] / [Planned] / [Backlog] / [Removed].

---

Scope at a glance

In scope: the platform theme the K2 Qt6 Linux AppImage selects at launch; that it selects one which is present in the bundle; that a KDE session is left as it is today; and the rule that keeps the two K2 Qt6 workflows' launchers identical — and, added 2026-10-12 at the maintainer's direction, the build environment of the K2 macOS package (K2D-C6, K2D-C7).

Out of scope (non-goals): the appearance of the packaged K2 build beyond starting — the Controls style, the icon theme, and host-native file dialogs through the XDG desktop portal, which K3 adopted (DPL-F3 in SpecK3Deployment) and K2 deliberately does not in this round (K2D-C4). Removing any plugin from the bundle (K2D-C5). The Windows and macOS portable bundles, except for the macOS rows K2D-C6 / K2D-C7, and any downstream manifest. K3 packaging, which is SpecK3Deployment. No change to any file under qt_widgets/ or core/ is authorised by this page (K2D-C1).

---

Operational requirements — why / for whom

Goals in real use, independent of how they are built.

ID	Requirement	Status
K2D-O1	A user can start the published K2 Linux AppImage and reach the main window on any Linux desktop, not only on a KDE/Plasma session, without setting any environment variable first. Held at [Planned] deliberately: its first two instances are closed — Linux Mint / Cinnamon and Manjaro / XFCE both start with no overrides (K2D-F1) — but "any Linux desktop" is a wider claim than two GTK desktops. GNOME, which the crash comment named, has not been run, and neither has a Plasma session since the change (K2D-F2). A goal is only as strong as its verification.	[Planned]

Functional requirements — what the system does

Observable behaviour that can be triggered and watched.

ID	Requirement	Status
K2D-F1	On a session that is not a KDE session, the K2 Qt6 AppImage launcher sets a platform theme that is present in the bundle (generic), rather than leaving Qt to auto-select one from the session. generic is built into QtGui and needs no plugin, so it cannot fail the way an auto-selected plugin does. Verified on two independent GTK desktops: an AppImage rebuilt from the patched workflow starts with no environment overrides on Linux Mint / Cinnamon and on Manjaro / XFCE, where the previous build died before printing any of its own startup output.	[Implemented]
K2D-F2	On a KDE session the launcher leaves the host's platform theme in effect, so K2 keeps the Plasma appearance it has today. K2D-F1 MUST NOT be applied unconditionally. Satisfied by construction: the fix changed only the body of the existing non-KDE branch, leaving its if [ -z "$KDE_SESSION_VERSION" ] && [ -z "$KDE_FULL_SESSION" ] condition untouched, so on a KDE session the launcher executes byte-identical code to the previous build. There is no mechanism by which Plasma behaviour could differ; the charter line for this row is confirmation of that reading, not mitigation of a risk. Held at [Planned] only because no run on Plasma has been reported.	[Planned]
K2D-F3	A published AppImage that dies before the application's own startup output on any tested desktop is a release blocker, not a per-desktop caveat noted in the release text. It means the application cannot be started at all by everyone on that desktop.	[Planned]

Constructional requirements — how it is built / limits / MUST-NOTs

Boundaries and implementation constraints, not user-visible behaviour.

ID	Requirement	Status
K2D-C1	This is packaging only: the AppRun scripts of the two K2 Qt6 AppImage workflows. It MUST NOT change any file under qt_widgets/ or core/, and MUST NOT add, change or remove any user-visible string. Satisfied: the fix (commit a4ad9136) touches the two workflow files and this documentation only — no file under qt_widgets/ or core/, and no tr( string.	[Implemented]
K2D-C2	The two K2 Qt6 AppImage workflows (buildKF6 and kdeneon) carry byte-identical AppRun scripts. Any change to one MUST be applied to the other in the same change. They are identical today; fixing only one would leave one published AppImage still crashing. Satisfied: the fix changed both in the same commit, and their AppRun blocks remain byte-identical to each other afterwards.	[Implemented]
K2D-C3	unset QT_QPA_PLATFORMTHEME MUST NOT be relied on as the mitigation. Qt still auto-selects a theme plugin from the session, so on a GTK desktop it loads a bundled plugin resolved against the host's GTK stack. The comment above the AppRun heredoc in each of the two K2 Qt6 workflows asserted that the unset works and gave a wrong reason for it; such a comment MUST be corrected in the same change as the launcher — otherwise the next reader re-derives the same incomplete mitigation from a comment that claims it is already solved. Satisfied: both comments now state that the unset is not enough, give the correct reason (Qt auto-selects from XDG_CURRENT_DESKTOP, and on a GTK desktop that is gtk3), and cite this page.	[Implemented]
K2D-C4	K2 does not adopt the K3 portal approach (DPL-F3) in this round. K2 is in maintenance mode, and the authorised fix is the launcher variable only. Host-native dialogs, a bundled Controls style and a bundled icon theme for the K2 AppImage are each a separate decision, requiring the maintainer's approval and an amendment to this page first. They are not ruled out; they are simply not sanctioned here.	[Planned]
K2D-C5	Removing a platform-theme plugin from the K2 AppDir — for example AppDir/usr/plugins/platformthemes/libqgtk3.so, so that no other route can load it — is not authorised by this page. It is recorded as a candidate, pending evidence that names the plugin which fails: the measurements behind K2D-F1 locate the failure in theme and style initialisation but do not identify the plugin, and K2D-F1 does not depend on the answer. The grep that would have named it was never run, and now that K2D-F1 is verified on two GTK desktops there is little left to gain from chasing it: the failing plugin is no longer reachable on the session that selected it. Taking this on is a separate decision on its own merits, and would need the plugin identified first.	[Planned]
K2D-C6	The K2 macOS package is built on the GitHub runner macos-15 (.github/workflows/Katalog_2_Build_macOS.yml). The runner defines the package's minimum macOS: macOS 15 (Sequoia), Apple Silicon only. It MUST be a macOS release for which Homebrew publishes bottles of the Qt modules used. Homebrew bottles only the three latest macOS releases, so moving the runner when that window moves is a deliberate change, made together with an amendment of this row. No Intel or universal build is authorised. Mirrors DPL-C7 (SpecK3Deployment.md).	[Planned]
K2D-C7	The K2 macOS workflow MUST fail if Homebrew built qtbase, or any other Qt module, from source instead of pouring a bottle. This is preventive: K2 2.13 was not affected (its macOS build, run 35541311468 of 2026-09-20, poured qtbase--6.11.2.arm64_sonoma.bottle and printed no libpng warning), but the K2 workflow had the same exposure, running on macos-14 with Homebrew Qt. A runner-built Qt is the cause of the K3 3.0.beta3 macOS defect, measured on the K3 workflow only (no icons: built against libpng 1.4.12 headers, run with bundled 1.6.59); see DPL-C8. K2 gets no launch-test / libpng-output check (the K3 DPL-C9): K2 is in maintenance mode, and this row prevents the root cause.	[Planned]

---

Known limitations of the packaged K2 build

Recorded so a future reader does not mistake them for defects introduced here, or for work that was agreed.

Item	Detail
generic platform theme, not the desktop's	On a non-KDE session the packaged K2 build uses Qt's generic platform theme by K2D-F1. It therefore does not pick up that desktop's colours, icon theme or native file dialog. This is the price of starting at all, and it is no loss against the previous build, which on those desktops did not start. Improving it is K2D-C4.
Failing plugin not named	The bundle keeps every platform-theme plugin it ships today (K2D-C5). The fix prevents Qt from selecting the failing one on a non-KDE session; it does not make the bundle incapable of loading it.
A released version is affected	Confirmed on Mint / Cinnamon for 2.12 (released) and 2.13.beta1: this is not a 2.13 regression, and the affected users are not only beta testers. No other released version was tested, so nothing is claimed for 2.11 or earlier. Until a rebuilt AppImage ships, the only workaround available to a user on a GTK desktop is to launch with QT_QPA_PLATFORMTHEME=generic themselves.
macOS 14 (Sonoma) and Intel Macs not supported	From the 2026-10-12 workflow change the K2 macOS package is built on macOS 15 (K2D-C6) and does not start on macOS 14 or earlier; Apple Silicon only, as before. The change is preventive: K2 2.13 was not affected (run 35541311468, 2026-09-20, poured the arm64_sonoma qtbase bottle, no libpng warning). The K2 workflow had the same exposure as K3's: Homebrew no longer publishes arm64_sonoma bottles for qtbase 6.11.2_1, so a later macos-14 run would build Qt from source. The resulting defect was measured on the K3 workflow only (CI run 38172585493 vs beta2 run 35544535205).

---

Manual test charter

Each line must be run against the AppImage, not against a build from source — the whole subject of this page is the difference between the two.

• K2D-O1 / K2D-F1 — On Linux Mint / Cinnamon, run the AppImage with no environment overrides at all. The main window appears, and the application's own startup lines (WARNING: Unknown SearchIn value, using default: "" and the three that follow) are printed. Verified on an AppImage rebuilt from the patched workflow. The same run against the published 2.13.beta1 and 2.12 AppImages stops after the two kf.i18n: KLocalizedString lines, which is what makes this a before/after and not just a passing test.
• K2D-F1 (second desktop) — Repeat on a second non-KDE desktop. Verified on Manjaro / XFCE: starts with no overrides. Two desktops show the mitigation holds beyond the one that reported it; they do not close K2D-O1, because both are GTK desktops and GNOME has not been run.
• K2D-F2 — On Plasma, run the same AppImage. It starts, and it looks as it does today: same colours, same icons, same dialogs. Open, and expected to pass: the KDE branch of the launcher is byte-identical to the previous build, so this is confirmation rather than a risk to be cleared.
• K2D-F3 — Capture the full stderr of both runs above. Neither stops at the kf.i18n: KLocalizedString lines. A run that does is a release blocker.
• K2D-C1 — Review the diff: no file under qt_widgets/ or core/ is touched, and no tr( is added, changed or removed. Verified on commit a4ad9136: two workflow files and documentation only.
• K2D-C2 — Diff the AppRun block of Katalog_2_Build_linux_qt6_buildKF6_appimage.yml against the one in Katalog_2_Build_linux_qt6_kdeneon_appimage.yml: byte-identical. Then confirm the change touched both files. Verified after the fix: the two blocks differ in nothing, and both files are in the same commit.
• K2D-C3 — Read the comment above each AppRun heredoc. It no longer claims that unsetting the variable is sufficient, and no longer states that auto-detection makes the unset safe on a non-KDE desktop. Verified: both comments now say the unset is not enough, name XDG_CURRENT_DESKTOP as the reason, and cite this page.
• K2D-C5 — List AppDir/usr/plugins/platformthemes/ in the built AppDir: unchanged from before this round, with no plugin removed.
• Released version exposure — Done: the released 2.12 AppImage was run on the same Linux Mint / Cinnamon virtual machine and crashes identically, so the defect reaches users of a released version. Should the same check be wanted for an earlier release, run that AppImage on the same virtual machine and record the result here. This does not gate the fix; it establishes how far back the defect reaches.
• K2D-C6 — The K2 macOS workflow's runs-on is macos-15; the built binary is arm64. The DMG starts on macOS 15 / Apple Silicon and shows its icons.
• K2D-C7 — The brew install log shows Pouring for every Qt module and no Building from source; a forced source build makes the workflow fail.