{"record":{"id":"2fc933ded21172ba","repo":"xpipe-io/xpipe","slug":"connection-path-is-not-a-shell-connection","errorCode":null,"errorMessage":"Connection ${path} is not a shell connection","messagePattern":"Connection (.+?) is not a shell connection","errorType":"exception","errorClass":"BeaconClientException","httpStatus":null,"severity":"error","filePath":"app/src/main/java/io/xpipe/app/beacon/mcp/McpToolHandler.java","lineNumber":158,"sourceCode":"\n            if (found.size() > 1) {\n                throw new BeaconClientException(\"Multiple connections found: \"\n                        + found.stream()\n                                .map(entry ->\n                                        DataStorage.get().getStorePath(entry).toString())\n                                .toList());\n            }\n\n            var e = found.getFirst();\n            return e.ref();\n        }\n\n        public DataStoreEntryRef<ShellStore> getShellStoreRef(String name, boolean mutation)\n                throws BeaconClientException {\n            var ref = getDataStoreRef(name);\n            var isShell = ref.getStore() instanceof ShellStore;\n            if (!isShell) {\n                throw new BeaconClientException(\"Connection \"\n                        + DataStorage.get().getStorePath(ref.get()).toString() + \" is not a shell connection\");\n            }\n\n            var disableMutation =\n                    DataStorage.get().getEffectiveCategoryConfig(ref.get()).getDontAllowScripts();\n            if (mutation && disableMutation != null && disableMutation) {\n                throw new BeaconClientException(\"Modifications to connection \"\n                        + DataStorage.get().getStorePath(ref.get()).toString()\n                        + \" is disabled by the category setting\");\n            }\n\n            return ref.asNeeded();\n        }\n    }\n}\n","sourceCodeStart":140,"sourceCodeEnd":174,"githubUrl":"https://github.com/xpipe-io/xpipe/blob/d85ca821baa46092a320ebb13546d7240adb74f8/app/src/main/java/io/xpipe/app/beacon/mcp/McpToolHandler.java#L140-L174","documentation":"McpToolHandler.getShellStoreRef resolves a connection ref and then asserts the underlying store is an instance of ShellStore. When the resolved connection is a different store kind (e.g. a database, HTTP, or script store), it throws this BeaconClientException naming the store path.","triggerScenarios":"Calling an MCP shell tool (shell command execution, file read/list) and passing a connection name whose DataStore is not a ShellStore — e.g. a database connection, an API/http connection, or a custom store.","commonSituations":"Selecting a database or Kubernetes connection where a shell connection was expected; confusing a Proxmox/hypervisor container entry with its SSH connection; reusing a name from a different tool context.","solutions":["Pass the name of an actual shell connection (SSH, local shell, serial, etc.)","Inspect the connection's type in the XPipe UI; create an SSH/local shell connection if needed","If the target is a database, use the database-specific MCP tool instead of the shell one","Catch BeaconClientException and report that the chosen connection type is unsupported for shell operations"],"exampleFix":"// before\nreq.getShellStoreRef(\"prod-postgres\", false) // database store\n// after\nreq.getShellStoreRef(\"prod-postgres-host\", false) // SSH shell connection to the host","handlingStrategy":"type-guard","validationCode":"// check the connection type before the shell tool call\nconst conn = await getConnection(name);\nif (conn.storeType !== 'shell') {\n  throw new Error(`connection '${name}' is a ${conn.storeType} store; a shell connection is required`);\n}","typeGuard":"function isShellConnection(conn) { return conn != null && typeof conn.storeType === 'string' && conn.storeType.toLowerCase().includes('shell'); }","tryCatchPattern":"try { return shellTool.call({name}); } catch (BeaconClientException e) { if (e.message.includes('is not a shell connection')) { /* switch to the matching tool for that store kind */ } throw e; }","preventionTips":["Check the connection's store type in the XPipe UI before shell operations","Pair each store kind with its dedicated tool (database tools for DBs, shell tools for SSH/local)","Keep naming conventions that distinguish host shell connections from service connections"],"tags":["mcp","type-mismatch","shell-connection"],"backgroundTag":"incompatible-source-type","analyzedSha":"d85ca821baa46092a320ebb13546d7240adb74f8","analyzedAt":"2026-09-06T14:30:08.251Z","contentChangedAt":"2026-09-06T14:30:08.251Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}