What causes "e" in xpipe-io/xpipe?

Inspect e.getCause() for the underlying connection error

xpipe-io/xpipe · error · BeaconServerException

e

Error message

What it means

A BeaconServerException wrapping any Exception thrown while creating the standalone shell control session for an external terminal launch in externalExchange. The message is just 'e'; the meaningful detail is in the cause. It indicates the connection/session to the target store could not be established.

Source

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

                }
            }

            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) {
            throw new BeaconServerException(e);
        }

        // These prepend scripts, not append
        TerminalPromptManager.configurePromptScript(session);
        ProcModuleProvider.get().withDefaultScripts(session);

        ProcessControl control;
        if (arguments.size() > 0) {
            control = session.command(CommandBuilder.of().addAll(arguments));
        } else {
            control = session;
        }

        var config = new TerminalInitScriptConfig(ref.get().getName(), false, TerminalInitFunction.none());
        submitAsync(request, control, config, null);
        waitExchange(request);
        var script = launchExchange(request);
        try (var sc = LocalShell.getShell().start()) {

View on GitHub (pinned to d85ca821ba)

Solutions

Inspect e.getCause() for the underlying connection error
Test the store connection independently (connection test in XPipe UI)
Verify host reachability, credentials, and that the required connection software is installed
Recreate or repair the store entry if its configuration is corrupt

Example fix

try {
    var script = TerminalLauncherManager.externalExchange(ref);
} catch (BeaconServerException e) {
    logger.error("could not open shell session for external terminal", e.getCause());
}

Defensive patterns

Strategy: try-catch

Validate before calling

// test store reachability before externalExchange
if (!ref.getStore().isEnabled()) throw new IllegalStateException("store disabled");

Try / catch

try {
    var result = TerminalLauncherManager.externalExchange(ref);
} catch (BeaconServerException e) {
    logger.error("session creation for external terminal failed", e.getCause());
}

Prevention

Run a connection test on the store before launching
Validate credentials and host reachability
Ensure required connection tools (ssh etc.) are installed

When it happens

Trigger: ref.getStore().standaloneControl() throwing — e.g. store connection failures, invalid credentials, unreachable host, or store configuration errors when opening the shell session.

Common situations: SSH host unreachable or refusing connections; wrong credentials in the store; connection provider (e.g. ssh, RDP) not installed; network change while opening the session.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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