xpipe-io/xpipe · error · BeaconClientException

Invalid launch request state ${request}

Error message

Invalid launch request state ${request}

What it means

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).

Source

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

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

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

View on GitHub (pinned to d85ca821ba)

Solutions

1. Check the TerminalLaunchResult subtype to determine the actual failure (failure message, timeout, cancel)
2. Retry the whole launch with a fresh request UUID
3. Verify the terminal application is installed and configured correctly in XPipe settings
4. Ensure the client accepted/confirmed the launch prompt in time

Example fix

// before: assuming success
var script = TerminalLauncherManager.launchExchange(request);
// after: handle non-success states
try {
    var script = TerminalLauncherManager.launchExchange(request);
} catch (BeaconClientException e) {
    var result = TerminalLauncherManager.getLastResult(request); // inspect actual state
    logger.warn("launch {} did not succeed: {}", request, result);
}

// verify request is used once and result awaited before exchanging
Objects.requireNonNull(request, "request uuid required");

try {
    var script = TerminalLauncherManager.launchExchange(request);
} catch (BeaconClientException e) {
    if (e.getMessage().startsWith("Invalid launch request state")) {
        // restart the launch with a new request UUID
    }
}

When it happens

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

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

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Unknown launch request
• Wrong launch context
• ex
• No connection found for input " + msg.getConnection()
• Multiple stores found: " + storeNames

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