{"record":{"id":"a38a06c44d181318","repo":"Devolutions/UniGetUI","slug":"the-current-unigetui-session-is-running-headless-a-a38a06","errorCode":null,"errorMessage":"The current UniGetUI session is running headless and cannot navigate UI pages.","messagePattern":"The current UniGetUI session is running headless and cannot navigate UI pages\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"warning","filePath":"src/UniGetUI.Interface.IpcApi/HeadlessIpcHost.cs","lineNumber":85,"sourceCode":"            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    }\n\n    private static Task WaitForShutdownAsync(CancellationToken cancellationToken)\n    {\n        if (cancellationToken.IsCancellationRequested)","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/Devolutions/UniGetUI/blob/9b1d7d0eab91620fc15c86b36676532095936ae3/src/UniGetUI.Interface.IpcApi/HeadlessIpcHost.cs#L67-L103","documentation":"HeadlessIpcHost.CreateIpcServer wires a NavigateAppHandler that unconditionally throws InvalidOperationException. The headless daemon cannot navigate to any UI page because there is no window. The handler is set (not null) so the failure is explicit. Clients should check AppInfoProvider().CanNavigate (false in headless) before issuing a navigate command.","triggerScenarios":"An IPC client sends a 'navigate-app' command (e.g. navigate to 'settings') to the headless daemon. The IpcServer invokes backgroundApi.NavigateAppHandler with the page argument, which throws.","commonSituations":"A remote-control or automation script tries to drive the UI to a specific page, but targets the headless session. A client is unaware that the session is headless. A tray launcher issues a navigate command intended for the GUI to the wrong IPC endpoint.","solutions":["Check AppInfoProvider().CanNavigate before sending a navigate command.","Route navigation commands to the GUI process, not the headless daemon.","Catch the InvalidOperationException in the client and report that navigation is unavailable in this session."],"exampleFix":"// before: navigate to settings on the daemon\nawait ipc.NavigateAppAsync(\"settings\");\n// after: guard against headless\nvar info = await ipc.GetAppInfoAsync();\nif (info.CanNavigate)\n    await ipc.NavigateAppAsync(\"settings\");\nelse\n    Logger.Warn(\"Navigation not available in headless session.\");","handlingStrategy":"validation","validationCode":"var info = await ipc.GetAppInfoAsync();\nif (info.CanNavigate)\n    await ipc.NavigateAppAsync(page);","typeGuard":"static bool CanNavigate(IpcAppInfo info) => info is { Headless: false, CanNavigate: true };","tryCatchPattern":"try { await ipc.NavigateAppAsync(page); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"headless\"))\n{ Logger.Warn(\"Cannot navigate in headless session.\"); }","preventionTips":["Always check AppInfoProvider().CanNavigate before issuing navigate commands.","Send navigation only to GUI sessions.","Gracefully report unavailability to the user in headless mode."],"tags":["ipc","headless","ui","navigation","daemon"],"backgroundTag":null,"analyzedSha":"9b1d7d0eab91620fc15c86b36676532095936ae3","analyzedAt":"2026-08-13T12:19:18.278Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}