{"record":{"id":"a22d20384c929fec","repo":"xpipe-io/xpipe","slug":"not-a-shell-connection","errorCode":null,"errorMessage":"Not a shell connection","messagePattern":"Not a shell connection","errorType":"exception","errorClass":"BeaconClientException","httpStatus":400,"severity":"error","filePath":"app/src/main/java/io/xpipe/app/beacon/api/ShellStartExchange.java","lineNumber":36,"sourceCode":"import lombok.extern.jackson.Jacksonized;\n\nimport java.util.UUID;\n\npublic class ShellStartExchange extends BeaconInterface<ShellStartExchange.Request> {\n\n    @Override\n    public String getPath() {\n        return \"/shell/start\";\n    }\n\n    @Override\n    @SneakyThrows\n    public Object handle(HttpExchange exchange, Request msg) {\n        var e = DataStorage.get()\n                .getStoreEntryIfPresent(msg.getStore())\n                .orElseThrow(() -> new BeaconClientException(\"Unknown connection\"));\n        if (!(e.getStore() instanceof ShellStore s)) {\n            throw new BeaconClientException(\"Not a shell connection\");\n        }\n\n        var existing = AppBeaconServer.get().getCache().getShellSessions().stream()\n                .filter(beaconShellSession -> beaconShellSession.getEntry().equals(e))\n                .findFirst();\n        var control = (existing.isPresent()\n                ? existing.get().getControl()\n                : s.standaloneControl().start());\n        control.setNonInteractive();\n        control.start();\n\n        var d = control.getShellDialect().getDumbMode();\n        if (!d.supportsAnyPossibleInteraction()) {\n            control.close();\n            d.throwIfUnsupported();\n        }\n\n        if (existing.isEmpty()) {","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/xpipe-io/xpipe/blob/d85ca821baa46092a320ebb13546d7240adb74f8/app/src/main/java/io/xpipe/app/beacon/api/ShellStartExchange.java#L18-L54","documentation":"XPipe's beacon HTTP API throws this when a client requests a shell action (shell/start) against a store entry whose underlying DataStore is not a ShellStore. Only connections that actually provide a shell (SSH, local shell, etc.) can start shell sessions, so the handler rejects non-shell stores early with a typed BeaconClientException.","triggerScenarios":"Calling the POST /shell/start beacon endpoint (ShellStartExchange.handle) with a store UUID whose DataStore does not implement ShellStore, e.g. a script group, custom store, or category-like entry.","commonSituations":"Automation scripts iterate over all connections and blindly call shell start on every store; users pass the UUID of a non-shell connection; a store type changed after an update so a previously shell-capable store no longer is.","solutions":["Verify the connection is a shell-type connection (SSH, local, WSL, docker, etc.) in the XPipe UI before targeting it","Check the store type client-side before calling: e instanceof ShellStore or inspect the store's type in the listing response","Use the correct beacon endpoint for the store kind you actually have","If you need a shell on a non-shell store, add a shell-capable sub-connection to it and target that instead"],"exampleFix":"// before\nclient.shellStart(storeUuid); // store may not be a shell\n// after\nDataStoreEntry e = DataStorage.get().getStoreEntry(storeUuid);\nif (e.getStore() instanceof ShellStore) {\n    client.shellStart(storeUuid);\n} else {\n    throw new IllegalArgumentException(storeUuid + \" is not a shell connection\");\n}","handlingStrategy":"type-guard","validationCode":"DataStoreEntry e = DataStorage.get().getStoreEntryIfPresent(uuid).orElse(null);\nboolean ok = e != null && e.getStore() instanceof ShellStore;","typeGuard":"static boolean isShellConnection(DataStoreEntry e) {\n    return e != null && e.getStore() instanceof ShellStore;\n}","tryCatchPattern":"try {\n    client.shellStart(req);\n} catch (BeaconClientException ex) {\n    if (ex.getMessage().contains(\"Not a shell connection\")) {\n        // fall back to a different connection or skip\n    } else throw ex;\n}","preventionTips":["Check store type before shell operations","Only iterate shell-type connections in automation","Use the store listing API to filter by type"],"tags":["beacon","shell","xpipe"],"backgroundTag":"unsupported-operation","analyzedSha":"d85ca821baa46092a320ebb13546d7240adb74f8","analyzedAt":"2026-09-06T14:30:08.251Z","contentChangedAt":"2026-09-06T14:30:08.251Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}