xpipe-io/xpipe · error · BeaconConnectorException

Couldn't send request

Error message

Couldn't send request

What it means

BeaconClient.performRequest sends the HTTP POST to the xpipe daemon's beacon server and wraps any exception from client.send (connection failures, timeouts, TLS errors, IO problems) into BeaconConnectorException('Couldn't send request'). It signals the request never got a response, as opposed to a bad response body.

Source

Thrown at app/src/main/java/io/xpipe/app/beacon/BeaconClient.java:64

        }

        var client = HttpClient.newBuilder()
                .followRedirects(HttpClient.Redirect.NORMAL)
                .build();
        HttpResponse<String> response;
        try {
            // Use direct IP to prevent DNS lookups and potential blocks (e.g. portmaster)
            var uri = URI.create("http://127.0.0.1:" + port + prov.getPath());
            var builder = HttpRequest.newBuilder();
            if (token != null) {
                builder.header("Authorization", "Bearer " + token);
            }
            var httpRequest = builder.uri(uri)
                    .POST(HttpRequest.BodyPublishers.ofString(content))
                    .build();
            response = client.send(httpRequest, HttpResponse.BodyHandlers.ofString());
        } catch (Exception ex) {
            throw new BeaconConnectorException("Couldn't send request", ex);
        }

        if (AppProperties.get().isPrintBeaconMessages()) {
            System.out.println("Received raw response:");
            System.out.println(response.body());
        }

        var se = parseServerError(response);
        if (se.isPresent()) {
            se.get().throwError();
        }

        var ce = parseClientError(response);
        if (ce.isPresent()) {
            throw ce.get().throwException();
        }

        try {

View on GitHub (pinned to d85ca821ba)

Solutions

  1. Confirm the xpipe daemon is running and listening (launch it, check its log output for the beacon port).
  2. Verify the beacon address/port used by BeaconClient matches the daemon's configuration.
  3. Test reachability with a raw connection (curl / ping / telnet) to the host:port and fix network/firewall/proxy issues.
  4. Retry after transient network problems, and consider a timeout/retry policy around performRequest.

Example fix

// before
client.performRequest(req); // BeaconConnectorException if daemon down
// after
try {
    client.performRequest(req);
} catch (BeaconConnectorException e) {
    if (!isDaemonReachable()) startDaemon();
    client.performRequest(req);
}
Defensive patterns

Strategy: retry

Validate before calling

// check daemon reachability first
boolean up = new Socket().isConnected(); // or try connecting to host:port
HttpClient.newHttpClient().send(HttpRequest.newBuilder(URI.create(beaconUrl + "/ping")).build(), HttpResponse.BodyHandlers.ofString());

Try / catch

try {
    return client.performRequest(req);
} catch (BeaconConnectorException e) {
    if (e.getCause() instanceof ConnectException || e.getCause() instanceof HttpTimeoutException) {
        ensureDaemonRunning();
        return client.performRequest(req); // one retry
    }
    throw e;
}

Prevention

When it happens

Trigger: The daemon process is not running or its HTTP server port is down; wrong port/address configured; firewall or proxy blocking localhost/remote connection; connection reset or socket timeout during send; TLS handshake failure against an HTTPS beacon endpoint.

Common situations: Calling XPipe from a script before the daemon was started; daemon crashed mid-session; connecting to a remote machine whose beacon server is unreachable; port conflicts after config changes.

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/1906cc4650c4fe0b. Report an issue: GitHub.