{"record":{"id":"c97e2b803a83832b","repo":"xpipe-io/xpipe","slug":"invalid-launch-request-state-request","errorCode":null,"errorMessage":"Invalid launch request state ${request}","messagePattern":"Invalid launch request state (.+?)","errorType":"exception","errorClass":"BeaconClientException","httpStatus":null,"severity":"error","filePath":"app/src/main/java/io/xpipe/app/terminal/TerminalLauncherManager.java","lineNumber":143,"sourceCode":"                    var defaultShell = sc.getShellDialect();\n                    var shellExec = defaultShell.getExecutableName();\n                    var script = ScriptHelper.createExecScript(\n                            sc,\n                            sc.getShellDialect()\n                                            .getEchoCommand(\n                                                    \"Unknown \"\n                                                            + AppNames.ofCurrent()\n                                                                    .getName() + \" launch request\",\n                                                    false)\n                                    + \"\\n\" + shellExec);\n                    return Path.of(script.toString());\n                } catch (Exception ex) {\n                    throw new BeaconServerException(ex);\n                }\n            }\n\n            if (!(e.getResult() instanceof TerminalLaunchResult.ResultSuccess)) {\n                throw new BeaconClientException(\"Invalid launch request state \" + request);\n            }\n\n            return ((TerminalLaunchResult.ResultSuccess) e.getResult()).getTargetScript();\n        }\n    }\n\n    public static List<String> externalExchange(DataStoreEntryRef<ShellStore> ref, List<String> arguments)\n            throws BeaconClientException, BeaconServerException {\n        var request = UUID.randomUUID();\n        ShellControl session;\n        try {\n            session = ref.getStore().standaloneControl();\n        } catch (Exception e) {\n            throw new BeaconServerException(e);\n        }\n\n        // These prepend scripts, not append\n        TerminalPromptManager.configurePromptScript(session);","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/xpipe-io/xpipe/blob/d85ca821baa46092a320ebb13546d7240adb74f8/app/src/main/java/io/xpipe/app/terminal/TerminalLauncherManager.java#L125-L161","documentation":"BeaconClientException thrown by launchExchange when the completed launch exchange returns a TerminalLaunchResult that is not ResultSuccess. The request UUID is included so the failed exchange can be correlated. It means the terminal launch handshake finished but reported a non-success state (e.g. failure, timeout, or pending).","triggerScenarios":"Calling launchExchange(request) after waitExchange(request) returned a TerminalLaunchResult whose result object is not ResultSuccess — the launch was rejected, errored, or timed out on the client side.","commonSituations":"User cancelled the terminal launch prompt; terminal emulator could not be started; launch timed out waiting for the client to connect; stale or reused request UUID whose result was already consumed or failed.","solutions":["Check the TerminalLaunchResult subtype to determine the actual failure (failure message, timeout, cancel)","Retry the whole launch with a fresh request UUID","Verify the terminal application is installed and configured correctly in XPipe settings","Ensure the client accepted/confirmed the launch prompt in time"],"exampleFix":"// before: assuming success\nvar script = TerminalLauncherManager.launchExchange(request);\n// after: handle non-success states\ntry {\n    var script = TerminalLauncherManager.launchExchange(request);\n} catch (BeaconClientException e) {\n    var result = TerminalLauncherManager.getLastResult(request); // inspect actual state\n    logger.warn(\"launch {} did not succeed: {}\", request, result);\n}","handlingStrategy":"try-catch","validationCode":"// verify request is used once and result awaited before exchanging\nObjects.requireNonNull(request, \"request uuid required\");","typeGuard":null,"tryCatchPattern":"try {\n    var script = TerminalLauncherManager.launchExchange(request);\n} catch (BeaconClientException e) {\n    if (e.getMessage().startsWith(\"Invalid launch request state\")) {\n        // restart the launch with a new request UUID\n    }\n}","preventionTips":["Never reuse request UUIDs across launches","Always complete waitExchange before launchExchange","Surface non-success TerminalLaunchResult states to the user instead of failing silently"],"tags":["terminal","launch","state"],"backgroundTag":"invalid-state-transition","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"}