xpipe-io/xpipe · error · BeaconClientException

Unable to parse action into known schema

Error message

Unable to parse action into known schema

What it means

ActionExchange handles the /action beacon endpoint. It parses the incoming action string via ActionJacksonMapper.parse; if the string does not map to any known action class, it throws BeaconClientException('Unable to parse action into known schema'). The daemon therefore rejected an unrecognized or malformed action name.

Source

Thrown at app/src/main/java/io/xpipe/app/beacon/api/ActionExchange.java:27

import com.sun.net.httpserver.HttpExchange;
import lombok.Builder;
import lombok.NonNull;
import lombok.Value;
import lombok.extern.jackson.Jacksonized;
import tools.jackson.databind.JsonNode;

public class ActionExchange extends BeaconInterface<ActionExchange.Request> {

    @Override
    public String getPath() {
        return "/action";
    }

    @Override
    public Object handle(HttpExchange exchange, Request msg) throws Exception {
        var action = ActionJacksonMapper.parse(msg.getAction());
        if (action == null) {
            throw new BeaconClientException("Unable to parse action into known schema");
        }

        if (!checkPermission()) {
            return Response.builder().build();
        }

        action.executeSyncImpl(msg.isConfirm());
        return Response.builder().build();
    }

    private boolean checkPermission() {
        var cache = AppCache.getBoolean("externalActionPermitted", false);
        if (cache) {
            return true;
        }

        var r = AppDialog.confirm("externalAction");
        if (r) {

View on GitHub (pinned to d85ca821ba)

Solutions

1. Check the action string against the supported actions for the running daemon version and fix typos/casing.
2. Update the XPipe daemon (or client) so both sides agree on the action schema.
3. Log msg.getAction() to see the exact raw value being rejected.
4. If invoking via a newer client API, downgrade the action or upgrade the daemon to match.

Example fix

// before
request.setAction("openconection"); // typo, unknown schema
// after
request.setAction("openConnection"); // must match a known action name

// confirm the action name is supported before sending
boolean known = ActionJacksonMapper.parse(actionName) != null;

boolean isKnownAction(String action) {
    return action != null && ActionJacksonMapper.parse(action) != null;
}

try {
    client.performRequest(new ActionExchange.Request(actionName));
} catch (BeaconClientException e) {
    LOG.error("Unknown action '{}' — check supported actions for daemon v{}", actionName, daemonVersion);
}

When it happens

Trigger: Sending an action name that is misspelled, deprecated, or from a newer client than the daemon supports; sending an empty or wrongly-cased action string; version mismatch where the client's action enum/schema isn't known to the daemon.

Common situations: Hard-coded action strings in scripts after an XPipe upgrade renamed actions; automation built against a newer API version talking to an older daemon; JSON casing/whitespace issues in the action field.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• No active shell session known for id " + uuid
• Couldn't send request
• Couldn't parse response
• Couldn't parse client error message
• error.getMessage() (+ optional documentationLink appended: "

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