{"record":{"id":"5fda185dd241c493","repo":"xpipe-io/xpipe","slug":"ex","errorCode":null,"errorMessage":"ex","messagePattern":"ex","errorType":"exception","errorClass":"BeaconServerException","httpStatus":null,"severity":"error","filePath":"app/src/main/java/io/xpipe/app/terminal/TerminalLauncherManager.java","lineNumber":138,"sourceCode":"                // Therefore, we just return a new local shell session\n                TrackEvent.withTrace(\"Unknown launch request\")\n                        .tag(\"request\", request.toString())\n                        .handle();\n                try (var sc = LocalShell.getShell().start()) {\n                    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) {","sourceCodeStart":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/xpipe-io/xpipe/blob/d85ca821baa46092a320ebb13546d7240adb74f8/app/src/main/java/io/xpipe/app/terminal/TerminalLauncherManager.java#L120-L156","documentation":"A generic BeaconServerException wrapping any Exception thrown while building or writing the terminal launch shell script during launchExchange. The original exception is lost in the message ('ex') but preserved as the cause. It signals that the server-side preparation of the launch script failed.","triggerScenarios":"Any exception inside the try block of launchExchange while constructing the script path/content, e.g. IOException writing the script file, failures resolving temp directories, or formatting errors building the shell exec string.","commonSituations":"Read-only or full temp directory preventing script creation; permission errors writing the launch script; disk full; unexpected nulls in store configuration used to render the script.","solutions":["Inspect the wrapped cause (ex.getCause()) for the real error","Verify the target system's temp/script directory is writable and has free space","Check file permissions of the XPipe working directories on the remote/host system","Retry the launch after fixing the underlying I/O problem"],"exampleFix":"try {\n    var script = TerminalLauncherManager.launchExchange(request);\n} catch (BeaconServerException e) {\n    logger.error(\"launch script creation failed\", e.getCause());\n}","handlingStrategy":"try-catch","validationCode":"// ensure the script output directory is writable before launching\nPath dir = Path.of(System.getProperty(\"java.io.tmpdir\"));\nif (!Files.isWritable(dir)) throw new IllegalStateException(\"script dir not writable: \" + dir);","typeGuard":null,"tryCatchPattern":"try {\n    var script = TerminalLauncherManager.launchExchange(request);\n} catch (BeaconServerException e) {\n    Throwable cause = e.getCause();\n    logger.error(\"script creation failed: {}\", cause != null ? cause.getMessage() : e.getMessage(), cause);\n}","preventionTips":["Monitor temp directory space and permissions","Always inspect getCause() on BeaconServerException wrappers","Handle IOExceptions from script writing explicitly"],"tags":["terminal","launch","io","wrapped-exception"],"backgroundTag":"file-write-failed","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"}