{"record":{"id":"6570121c24b4996c","repo":"xpipe-io/xpipe","slug":"unknown-launch-request","errorCode":null,"errorMessage":"Unknown launch request","messagePattern":"Unknown launch request","errorType":"exception","errorClass":"BeaconClientException","httpStatus":null,"severity":"error","filePath":"app/src/main/java/io/xpipe/app/terminal/TerminalLauncherManager.java","lineNumber":59,"sourceCode":"            var req = entries.get(request);\n            if (req == null) {\n                req = new TerminalLaunchRequest(request, processControl, config, directory);\n                entries.put(request, req);\n            } else {\n                req.setResult(null);\n            }\n\n            req.setupRequestAsync();\n        }\n    }\n\n    public static Path sshLaunchExchange() throws BeaconClientException, BeaconServerException {\n        TerminalLaunchRequest last;\n        synchronized (entries) {\n            var all = entries.values().stream().toList();\n            last = !all.isEmpty() ? all.getLast() : null;\n            if (last == null) {\n                throw new BeaconClientException(\"Unknown launch request\");\n            }\n        }\n        return last.waitForCompletion();\n    }\n\n    @SuppressWarnings(\"unused\")\n    public static boolean isCompletedSuccessfully(UUID request) {\n        synchronized (entries) {\n            var req = entries.get(request);\n            return req.getResult() instanceof TerminalLaunchResult.ResultSuccess;\n        }\n    }\n\n    public static void registerPid(UUID request, long pid) throws BeaconClientException {\n        TerminalLaunchRequest req;\n        synchronized (entries) {\n            req = entries.get(request);\n        }","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/xpipe-io/xpipe/blob/d85ca821baa46092a320ebb13546d7240adb74f8/app/src/main/java/io/xpipe/app/terminal/TerminalLauncherManager.java#L41-L77","documentation":"TerminalLauncherManager.sshLaunchExchange() is invoked by a terminal child process to complete its pending launch request. It takes the most recent entry from the manager's entries map; if the map is empty, no launch request is known, so it throws BeaconClientException(\"Unknown launch request\"). The library throws this to signal that the terminal process called back without any preceding request registration.","triggerScenarios":"sshLaunchExchange() called when the synchronized entries map is empty: no prior launch request was registered in this XPipe instance (e.g. terminal started manually, or state was lost/cleared before the terminal connected back).","commonSituations":"Opening a terminal session outside of XPipe's launch flow; XPipe restarted between spawning the terminal and the terminal's callback; concurrent requests raced so the last entry was consumed; stale terminal window reconnecting after the request was removed.","solutions":["Ensure the terminal is launched through the normal XPipe flow so a TerminalLaunchRequest is registered before the callback","Re-initiate the connection from XPipe so a fresh launch request exists","Avoid manually launching terminals that then call back into the beacon","Check for races where entries are cleared/consumed before sshLaunchExchange runs"],"exampleFix":"// before\n// terminal calls back without registration\nTerminalLauncherManager.sshLaunchExchange(); // throws\n// after\nTerminalLauncherManager.submitRequest(entry, request); // register first\nTerminalLauncherManager.sshLaunchExchange(); // now resolves","handlingStrategy":"retry","validationCode":"boolean hasPendingRequest = TerminalLauncherManager.hasPendingEntries(); // only call sshLaunchExchange when true","typeGuard":"boolean known = !TerminalLauncherManager.getEntries().isEmpty();","tryCatchPattern":"try {\n    TerminalLauncherManager.sshLaunchExchange();\n} catch (BeaconClientException e) {\n    if (e.getMessage().contains(\"Unknown launch request\")) {\n        // re-initiate launch from XPipe, then retry\n    }\n}","preventionTips":["Always launch terminals through XPipe's normal flow so a request is registered first","Avoid clearing/consuming entries concurrently with the terminal callback","Restart the connection from XPipe if the terminal connected back without a request","Treat this error as stale-state: re-launch rather than retry blindly"],"tags":["terminal","beacon","state","race-condition"],"backgroundTag":"resource-not-found","analyzedSha":"d85ca821baa46092a320ebb13546d7240adb74f8","analyzedAt":"2026-09-06T14:30:08.251Z","contentChangedAt":"2026-09-06T14:30:08.251Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}