xpipe-io/xpipe · error · BeaconClientException

No active shell session known for id " + uuid

Error message

No active shell session known for id " + uuid

What it means

XPipe's beacon server keeps an in-memory registry of active shell sessions keyed by UUID. getShellSession throws BeaconClientException when the requested UUID does not match any session currently tracked in shellSessions. This means the daemon either never created the session, already discarded it, or the client supplied a stale/wrong id.

Source

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

import lombok.Value;

import java.util.HashSet;
import java.util.Set;
import java.util.UUID;

@Value
public class AppBeaconCache {

    Set<BeaconShellSession> shellSessions = new HashSet<>();

    public BeaconShellSession getShellSession(UUID uuid) throws Exception {
        var found = shellSessions.stream()
                .filter(beaconShellSession ->
                        beaconShellSession.getEntry().getUuid().equals(uuid))
                .findFirst();
        if (found.isEmpty()) {
            throw new BeaconClientException("No active shell session known for id " + uuid);
        }

        var sc = found.get().getControl();
        if (!sc.isRunning(true) || sc.isAnyStreamClosed()) {
            sc.restart();
        }

        return found.get();
    }

    public BeaconShellSession getOrStart(DataStoreEntryRef<ShellStore> ref) throws Exception {
        var existing = AppBeaconServer.get().getCache().getShellSessions().stream()
                .filter(beaconShellSession -> beaconShellSession.getEntry().equals(ref.get()))
                .findFirst();
        var control = (existing.isPresent()
                ? existing.get().getControl()
                : ref.getStore().standaloneControl().start());
        control.setNonInteractive();

View on GitHub (pinned to d85ca821ba)

Solutions

  1. Verify the UUID corresponds to a session created by the currently running xpipe daemon (daemon restarts clear shellSessions).
  2. List current sessions / re-open the connection via the XPipe API to obtain a fresh, valid UUID before retrying.
  3. Re-create the shell session (re-open the connection) if it was closed, then use the new session id.
  4. Check that the client talks to the same daemon instance that owns the session (not a second local daemon or remote installation).

Example fix

// before
var session = client.getShellSession(oldUuid); // throws if stale
// after
UUID id = existingSessions.stream().map(BeaconShellSession::getEntry).map(e -> e.getUuid())
        .filter(oldUuid::equals).findFirst().orElseGet(() -> openNewSessionAndGetUuid());
var session = client.getShellSession(id);
Defensive patterns

Strategy: try-catch

Validate before calling

boolean known = sessions.stream().anyMatch(s -> s.getEntry().getUuid().equals(uuid));

Type guard

boolean isValidSession(UUID uuid, List<BeaconShellSession> sessions) {
    return uuid != null && sessions.stream()
        .anyMatch(s -> s.getEntry().getUuid() != null && s.getEntry().getUuid().equals(uuid));
}

Try / catch

try {
    var session = cache.getShellSession(uuid);
} catch (BeaconClientException e) {
    // session unknown: re-open connection to obtain a fresh session id
    var fresh = reopenConnectionAndGetSession();
}

Prevention

When it happens

Trigger: Calling a beacon API that references a shell session UUID which is not registered: the daemon restarted and lost in-memory sessions, the session was removed/closed earlier, the UUID was mistyped or came from another daemon instance, or the client cached an id across a reconnect.

Common situations: Client applications persisting session UUIDs across daemon restarts; sharing UUIDs between different xpipe daemon instances; long-running scripts holding ids after the shell connection was closed and reaped; automation that resumes from a saved config pointing at an old session.

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/cfc9e5d86f35ba61. Report an issue: GitHub.