xpipe-io/xpipe · error · BeaconServerException

ex

Error message

ex

What it means

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.

Source

Thrown at app/src/main/java/io/xpipe/app/terminal/TerminalLauncherManager.java:138

                // Therefore, we just return a new local shell session
                TrackEvent.withTrace("Unknown launch request")
                        .tag("request", request.toString())
                        .handle();
                try (var sc = LocalShell.getShell().start()) {
                    var defaultShell = sc.getShellDialect();
                    var shellExec = defaultShell.getExecutableName();
                    var script = ScriptHelper.createExecScript(
                            sc,
                            sc.getShellDialect()
                                            .getEchoCommand(
                                                    "Unknown "
                                                            + AppNames.ofCurrent()
                                                                    .getName() + " launch request",
                                                    false)
                                    + "\n" + shellExec);
                    return Path.of(script.toString());
                } catch (Exception ex) {
                    throw new BeaconServerException(ex);
                }
            }

            if (!(e.getResult() instanceof TerminalLaunchResult.ResultSuccess)) {
                throw new BeaconClientException("Invalid launch request state " + request);
            }

            return ((TerminalLaunchResult.ResultSuccess) e.getResult()).getTargetScript();
        }
    }

    public static List<String> externalExchange(DataStoreEntryRef<ShellStore> ref, List<String> arguments)
            throws BeaconClientException, BeaconServerException {
        var request = UUID.randomUUID();
        ShellControl session;
        try {
            session = ref.getStore().standaloneControl();
        } catch (Exception e) {

View on GitHub (pinned to d85ca821ba)

Solutions

1. Inspect the wrapped cause (ex.getCause()) for the real error
2. Verify the target system's temp/script directory is writable and has free space
3. Check file permissions of the XPipe working directories on the remote/host system
4. Retry the launch after fixing the underlying I/O problem

Example fix

try {
    var script = TerminalLauncherManager.launchExchange(request);
} catch (BeaconServerException e) {
    logger.error("launch script creation failed", e.getCause());
}

// ensure the script output directory is writable before launching
Path dir = Path.of(System.getProperty("java.io.tmpdir"));
if (!Files.isWritable(dir)) throw new IllegalStateException("script dir not writable: " + dir);

try {
    var script = TerminalLauncherManager.launchExchange(request);
} catch (BeaconServerException e) {
    Throwable cause = e.getCause();
    logger.error("script creation failed: {}", cause != null ? cause.getMessage() : e.getMessage(), cause);
}

When it happens

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

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

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• failure.getThrowable()
• Wrong launch context
• Invalid launch request state ${request}
• e
• No connection found for input " + msg.getConnection()

AI-assisted analysis of xpipe-io/xpipe@d85ca821ba (2026-09-06). Data as JSON: /api/errors/5fda185dd241c493. Report an issue: GitHub.