xpipe-io/xpipe · error · BeaconClientException

Multiple connections found: " + connectionPaths

Error message

Multiple connections found: " + connectionPaths

What it means

McpToolHandler.getDataStoreRef throws this BeaconClientException when DataStorageQuery.queryUserInput(name) matches more than one connection, making the reference ambiguous. The error message lists all matching store paths so the caller can disambiguate.

Source

Thrown at app/src/main/java/io/xpipe/app/beacon/mcp/McpToolHandler.java:142

        }

        public FilePath getFilePath(ShellControl sc, String key) throws Exception {
            var s = getStringArgument(key);
            var path = FilePath.parse(s);
            if (path == null) {
                throw new BeaconClientException("Invalid argument for key " + key);
            }
            return path.resolveTildeHome(sc.view().userHome());
        }

        public DataStoreEntryRef<?> getDataStoreRef(String name) throws BeaconClientException {
            var found = DataStorageQuery.queryUserInput(name);
            if (found.isEmpty()) {
                throw new BeaconClientException("No connection found for input " + name);
            }

            if (found.size() > 1) {
                throw new BeaconClientException("Multiple connections found: "
                        + found.stream()
                                .map(entry ->
                                        DataStorage.get().getStorePath(entry).toString())
                                .toList());
            }

            var e = found.getFirst();
            return e.ref();
        }

        public DataStoreEntryRef<ShellStore> getShellStoreRef(String name, boolean mutation)
                throws BeaconClientException {
            var ref = getDataStoreRef(name);
            var isShell = ref.getStore() instanceof ShellStore;
            if (!isShell) {
                throw new BeaconClientException("Connection "
                        + DataStorage.get().getStorePath(ref.get()).toString() + " is not a shell connection");
            }

View on GitHub (pinned to d85ca821ba)

Solutions

1. Use the full store path shown in the error message (e.g. 'Category / group / name') instead of the bare name
2. Rename duplicate connections in the XPipe UI to make names unique
3. Include category/group qualifiers in the query input to narrow the match
4. Catch BeaconClientException, parse the listed candidates, and retry with one exact path

Example fix

// before
req.getDataStoreRef("server") // ambiguous
// after
req.getDataStoreRef("Servers / web / server")

// disambiguate before calling
const matches = connections.filter(c => c.name.includes(query));
if (matches.length > 1) {
  throw new Error(`ambiguous connection '${query}'; candidates: ${matches.map(c => c.path).join(', ')}`);
}

try { return tool.call({name}); } catch (BeaconClientException e) { if (e.message.startsWith('Multiple connections found:')) { /* parse candidate paths from e.message and retry with the exact one */ } throw e; }

When it happens

Trigger: Passing a connection name/query that is a prefix of, or partially matches, multiple stored connections, so queryUserInput returns size() > 1.

Common situations: Several connections share the same display name in different categories; using a short name like 'server' when 'servers/web/server' and 'servers/db/server' both exist; duplicated connections after an import/merge of a data store.

Related errors

• No connection found for input " + name
• Missing argument for key " + key
• Invalid argument for key " + key
• Connection ${path} is not a shell connection
• Modifications to connection ${path} is disabled by the categ

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