xpipe-io/xpipe · error · BeaconClientException

No connection found for input " + msg.getConnection()

Error message

No connection found for input " + msg.getConnection()

What it means

TerminalExternalLaunchExchange resolves the free-form 'connection' input via DataStorageQuery.queryUserInput. If no connection matches the given string, the exchange cannot launch a terminal and throws this BeaconClientException.

Source

Thrown at app/src/main/java/io/xpipe/app/beacon/api/TerminalExternalLaunchExchange.java:33

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

import java.util.List;

public class TerminalExternalLaunchExchange extends BeaconInterface<TerminalExternalLaunchExchange.Request> {

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

    @Override
    public Object handle(HttpExchange exchange, Request msg) throws BeaconClientException, BeaconServerException {
        var found = DataStorageQuery.queryUserInput(msg.getConnection());
        if (found.isEmpty()) {
            throw new BeaconClientException("No connection found for input " + msg.getConnection());
        }

        if (found.size() > 1) {
            throw new BeaconClientException("Multiple stores found: "
                    + found.stream().map(DataStoreEntry::getName).toList());
        }

        var e = found.getFirst();
        var isShell = e.getStore() instanceof ShellStore;
        if (!isShell) {
            throw new BeaconClientException(
                    "Connection " + DataStorage.get().getStorePath(e).toString() + " is not a shell connection");
        }

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

View on GitHub (pinned to d85ca821ba)

Solutions

Run the exact string through DataStorageQuery.queryUserInput locally to see matches before calling
Use the full store path or exact UUID of the connection
List available connections (store/query API) to find the correct identifier
Re-create the connection if it was deleted

Example fix

// before
client.terminalLaunch("mydb"); // ambiguous/missing
// after
var found = DataStorageQuery.queryUserInput("MyCategory/mydb");
if (found.size() == 1) {
    client.terminalLaunch(found.getFirst().getUuid());
}

Defensive patterns

Strategy: validation

Validate before calling

var found = DataStorageQuery.queryUserInput(connection);
if (found.isEmpty()) throw new IllegalArgumentException("unknown connection: " + connection);

Try / catch

try {
    client.terminalLaunch(input);
} catch (BeaconClientException ex) {
    if (ex.getMessage().startsWith("No connection found")) {
        // list connections and correct the identifier
    } else throw ex;
}

Prevention

Use full store path or UUID for lookups
Cache UUIDs instead of free-form names
Re-resolve names after renames/deletions

When it happens

Trigger: Calling the terminal/external launch endpoint with a 'connection' string that matches no store — wrong name, typo, UUID of a deleted connection, or a fully-qualified path with a wrong segment.

Common situations: Typo or case mismatch in the connection name; connection deleted or renamed since the script was written; referencing a connection that lives in a different category path; passing a category instead of a connection.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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