xpipe-io/xpipe · error · BeaconServerException

error.getMessage() (+ optional documentationLink appended: "

Error message

error.getMessage() (+ optional documentationLink appended: "For more information and troubleshooting steps, see: " + documentationLink)

What it means

BeaconServerErrorResponse.throwError converts a structured error returned by the xpipe daemon into a BeaconServerException on the client side, using the server-supplied message, optionally appending a documentation link if present. This is the standard way server-side failures surface to API consumers.

Source

Thrown at app/src/main/java/io/xpipe/app/beacon/BeaconServerErrorResponse.java:23

import lombok.Value;
import lombok.extern.jackson.Jacksonized;

@SuppressWarnings("ClassCanBeRecord")
@Value
@Builder
@Jacksonized
@AllArgsConstructor
public class BeaconServerErrorResponse {

    Throwable error;
    String documentationLink;

    public void throwError() throws BeaconServerException {
        var message = error.getMessage();
        if (documentationLink != null) {
            message = message + "\n\nFor more information and troubleshooting steps, see: " + documentationLink;
        }
        throw new BeaconServerException(message, error);
    }
}

View on GitHub (pinned to d85ca821ba)

Solutions

1. Read error.getMessage() in the thrown BeaconServerException — it describes the actual daemon-side problem.
2. Fix the request payload that the daemon rejected (correct ids, valid state) before retrying.
3. Follow the appended documentationLink for troubleshooting steps specific to the server error.
4. Catch BeaconServerException and use getError() to branch on the structured error instead of string matching.

Example fix

// before
try { client.performRequest(req); } catch (Exception e) { e.printStackTrace(); }
// after
try {
    client.performRequest(req);
} catch (BeaconServerException e) {
    LOG.error("Daemon rejected request: {} (see {})", e.getMessage(), docLinkFrom(e));
}

try {
    client.performRequest(req);
} catch (BeaconServerException e) {
    LOG.error("Daemon error: {}", e.getMessage());
    // documentationLink, when present, is appended to e.getMessage()
}

When it happens

Trigger: Any beacon request that the daemon answers with an error object (e.g. invalid request data, failed operation on the daemon side) followed by the client calling throwError() on the received response.

Common situations: Invalid UUIDs or category ids passed to daemon APIs; operations rejected because a resource doesn't exist; server-side exceptions serialized into the error response and re-thrown locally.

Related errors

• No active shell session known for id " + uuid
• Couldn't send request
• Couldn't parse response
• Couldn't parse client error message
• No saved data known for id " + uuid

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