What causes "Unable to parse store data into valid store" in xpipe-io/xpipe?

Export the store from XPipe and copy its exact JSON structure into the 'data' field

xpipe-io/xpipe · error · BeaconClientException

Unable to parse store data into valid store

Error message

Unable to parse store data into valid store

What it means

StoreAddExchange parses the request's JSON 'data' field into a DataStore via Jackson polymorphic deserialization. If the JSON tree does not deserialize into any known DataStore implementation (or yields null), the handler rejects the request because a store must exist before it can be added.

Source

Thrown at app/src/main/java/io/xpipe/app/beacon/api/StoreAddExchange.java:38

import java.util.UUID;

public class StoreAddExchange extends BeaconInterface<StoreAddExchange.Request> {

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

    @Override
    public List<String> getPathAliases() {
        return List.of("/connection/add");
    }

    @Override
    public Object handle(HttpExchange exchange, Request msg) throws Throwable {
        var store = JacksonMapper.getDefault().treeToValue(msg.getData(), DataStore.class);
        if (store == null) {
            throw new BeaconClientException("Unable to parse store data into valid store");
        }

        var foundStore = DataStorage.get().getStoreEntryIfPresent(store, false);
        if (foundStore.isPresent()) {
            return Response.builder().store(foundStore.get().getUuid()).build();
        }

        var foundName = DataStorage.get().getStoreEntryIfPresent(msg.getName());
        if (foundName.isPresent()) {
            var foundNameStore = foundName.get().getStore();
            // Only allow updates for the same type of store
            if (foundNameStore != null && foundNameStore.getClass().equals(store.getClass())) {
                DataStorage.get().updateEntryStore(foundName.get(), store);
                return Response.builder().store(foundName.get().getUuid()).build();
            }
        }

        if (msg.getCategory() != null

View on GitHub (pinned to d85ca821ba)

Solutions

Export the store from XPipe and copy its exact JSON structure into the 'data' field
Ensure the discriminator fields (e.g. the polymorphic type id) are present and spelled correctly
Validate the JSON deserializes: run it through JacksonMapper.getDefault().treeToValue(json, DataStore.class) locally first
Check XPipe version compatibility of the store format

Example fix

// before
{"data": {"host": "myhost", "username": "root"}}
// after
{"data": {"type": "ssh", "remote": {"host": "myhost"}, "username": "root"}}

Defensive patterns

Strategy: validation

Validate before calling

Object store = JacksonMapper.getDefault().treeToValue(data, DataStore.class);
if (store == null) throw new IllegalArgumentException("store data does not deserialize");

Try / catch

try {
    client.storeAdd(request);
} catch (BeaconClientException ex) {
    if (ex.getMessage().contains("Unable to parse store data")) {
        // fix payload: export JSON from XPipe and reuse
    } else throw ex;
}

Prevention

Export store JSON from XPipe instead of hand-writing it
Round-trip test the payload with Jackson locally
Keep API and XPipe versions aligned

When it happens

Trigger: Calling the store/add beacon endpoint with a 'data' payload that Jackson maps to null or a non-DataStore object — e.g. missing the required 'type'/'category' discriminator fields, misspelled keys, or a JSON shape from a different XPipe version.

Common situations: Hand-writing store JSON instead of exporting it from XPipe; API version mismatch where the store format changed; sending the store data under the wrong JSON key.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

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

Related errors

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