{"record":{"id":"85efaff495811402","repo":"Devolutions/UniGetUI","slug":"the-current-unigetui-session-is-running-headless-a","errorCode":null,"errorMessage":"The current UniGetUI session is running headless and has no window to show.","messagePattern":"The current UniGetUI session is running headless and has no window to show\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"warning","filePath":"src/UniGetUI.Interface.IpcApi/HeadlessIpcHost.cs","lineNumber":81,"sourceCode":"    private static IpcServer CreateIpcServer(Action requestShutdown)\n    {\n        var backgroundApi = new IpcServer\n        {\n            SessionKind = IpcTransportOptions.HeadlessSessionKind,\n        };\n        backgroundApi.AppInfoProvider = () =>\n            new IpcAppInfo\n            {\n                Headless = true,\n                WindowAvailable = false,\n                WindowVisible = false,\n                CanShowWindow = false,\n                CanNavigate = false,\n                CanQuit = true,\n                SupportedPages = IpcAppPages.SupportedPages,\n            };\n        backgroundApi.ShowAppHandler = () =>\n            throw new InvalidOperationException(\n                \"The current UniGetUI session is running headless and has no window to show.\"\n            );\n        backgroundApi.NavigateAppHandler = _ =>\n            throw new InvalidOperationException(\n                \"The current UniGetUI session is running headless and cannot navigate UI pages.\"\n            );\n        backgroundApi.QuitAppHandler = () =>\n        {\n            _ = Task.Run(async () =>\n            {\n                await Task.Delay(150);\n                requestShutdown();\n            });\n            return IpcCommandResult.Success(\"quit-app\");\n        };\n\n        return backgroundApi;\n    }","sourceCodeStart":63,"sourceCodeEnd":99,"githubUrl":"https://github.com/Devolutions/UniGetUI/blob/9b1d7d0eab91620fc15c86b36676532095936ae3/src/UniGetUI.Interface.IpcApi/HeadlessIpcHost.cs#L63-L99","documentation":"HeadlessIpcHost.CreateIpcServer wires a ShowAppHandler that unconditionally throws InvalidOperationException. The headless daemon has no GUI window, so any IPC command asking to show or activate the application window is impossible. The handler is set deliberately (not null) so that a show-window request fails loudly instead of silently no-op'ing. Callers should check AppInfoProvider().CanShowWindow (false in headless) before attempting to show.","triggerScenarios":"An IPC client connected to the headless daemon sends a 'show-app' or 'activate-window' command. The IpcServer invokes backgroundApi.ShowAppHandler, which throws. This occurs when a client assumes a GUI session is available but is actually talking to the background-only daemon.","commonSituations":"A tray-icon launcher or CLI bridge sends show-window commands to the background daemon instance. A client connects to the wrong IPC session (headless instead of GUI). A script assumes the running process is the full Avalonia app when it is actually the headless daemon.","solutions":["Before sending a show-window command, query AppInfoProvider and check CanShowWindow == true.","Launch the full Avalonia GUI process instead of (or in addition to) the headless daemon if window display is needed.","Handle the InvalidOperationException in the IPC client and fall back to launching the GUI."],"exampleFix":"// before: unconditionally requesting the daemon to show its window\nawait ipc.ShowAppAsync();\n// after: check capability first\nvar info = await ipc.GetAppInfoAsync();\nif (info.CanShowWindow)\n    await ipc.ShowAppAsync();\nelse\n    CoreTools.Launch(guiExecutablePath);","handlingStrategy":"validation","validationCode":"var info = await ipc.GetAppInfoAsync();\nif (info.CanShowWindow)\n    await ipc.ShowAppAsync();","typeGuard":"static bool CanShowWindow(IpcAppInfo info) => info is { Headless: false, CanShowWindow: true };","tryCatchPattern":"try { await ipc.ShowAppAsync(); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"headless\"))\n{ Logger.Warn(\"Cannot show window in headless session.\"); }","preventionTips":["Always check AppInfoProvider().CanShowWindow before issuing show-window commands.","Route window operations to the GUI process, not the headless daemon.","Design IPC clients to degrade gracefully when WindowAvailable is false."],"tags":["ipc","headless","ui","daemon"],"backgroundTag":null,"analyzedSha":"9b1d7d0eab91620fc15c86b36676532095936ae3","analyzedAt":"2026-08-13T12:19:18.278Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}