Devolutions/UniGetUI · warning · InvalidOperationException

The current UniGetUI session is running headless and cannot

Error message

The current UniGetUI session is running headless and cannot navigate UI pages.

What it means

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.

Source

Thrown at src/UniGetUI.Interface.IpcApi/HeadlessIpcHost.cs:85

            SessionKind = IpcTransportOptions.HeadlessSessionKind,
        };
        backgroundApi.AppInfoProvider = () =>
            new IpcAppInfo
            {
                Headless = true,
                WindowAvailable = false,
                WindowVisible = false,
                CanShowWindow = false,
                CanNavigate = false,
                CanQuit = true,
                SupportedPages = IpcAppPages.SupportedPages,
            };
        backgroundApi.ShowAppHandler = () =>
            throw new InvalidOperationException(
                "The current UniGetUI session is running headless and has no window to show."
            );
        backgroundApi.NavigateAppHandler = _ =>
            throw new InvalidOperationException(
                "The current UniGetUI session is running headless and cannot navigate UI pages."
            );
        backgroundApi.QuitAppHandler = () =>
        {
            _ = Task.Run(async () =>
            {
                await Task.Delay(150);
                requestShutdown();
            });
            return IpcCommandResult.Success("quit-app");
        };

        return backgroundApi;
    }

    private static Task WaitForShutdownAsync(CancellationToken cancellationToken)
    {
        if (cancellationToken.IsCancellationRequested)

View on GitHub (pinned to 9b1d7d0eab)

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.

Example fix

// before: navigate to settings on the daemon
await ipc.NavigateAppAsync("settings");
// after: guard against headless
var info = await ipc.GetAppInfoAsync();
if (info.CanNavigate)
    await ipc.NavigateAppAsync("settings");
else
    Logger.Warn("Navigation not available in headless session.");

Defensive patterns

Strategy: validation

Validate before calling

var info = await ipc.GetAppInfoAsync();
if (info.CanNavigate)
    await ipc.NavigateAppAsync(page);

Type guard

static bool CanNavigate(IpcAppInfo info) => info is { Headless: false, CanNavigate: true };

Try / catch

try { await ipc.NavigateAppAsync(page); }
catch (InvalidOperationException ex) when (ex.Message.Contains("headless"))
{ Logger.Warn("Cannot navigate in headless session."); }

Prevention

Always check AppInfoProvider().CanNavigate before issuing navigate commands.
Send navigation only to GUI sessions.
Gracefully report unavailability to the user in headless mode.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of Devolutions/UniGetUI@9b1d7d0eab (2026-08-13). Data as JSON: /api/errors/a38a06c44d181318. Report an issue: GitHub.