{"record":{"id":"19765e274f4d2e17","repo":"xpipe-io/xpipe","slug":"not-a-toggleable-connection","errorCode":null,"errorMessage":"Not a toggleable connection","messagePattern":"Not a toggleable connection","errorType":"exception","errorClass":"BeaconClientException","httpStatus":null,"severity":"error","filePath":"app/src/main/java/io/xpipe/app/beacon/mcp/McpTools.java","lineNumber":505,"sourceCode":"\n                    return McpSchema.CallToolResult.builder()\n                            .addTextContent(\"Terminal is launching\")\n                            .build();\n                }))\n                .build();\n    }\n\n    public static McpServerFeatures.SyncToolSpecification toggleState() throws IOException {\n        var tool = McpSchemaFiles.loadTool(\"toggle_state.json\");\n        return McpServerFeatures.SyncToolSpecification.builder()\n                .tool(tool)\n                .callHandler(McpToolHandler.of((req) -> {\n                    var system = req.getStringArgument(\"system\");\n                    var state = req.getBooleanArgument(\"state\");\n                    var ref = req.getDataStoreRef(system);\n\n                    if (!(ref.getStore() instanceof SingletonSessionStore<?> singletonSessionStore)) {\n                        throw new BeaconClientException(\"Not a toggleable connection\");\n                    }\n                    if (state) {\n                        singletonSessionStore.startSessionIfNeeded();\n                    } else {\n                        singletonSessionStore.stopSessionIfNeeded();\n                    }\n\n                    return McpSchema.CallToolResult.builder()\n                            .addTextContent(\"Connection state set to \" + state)\n                            .build();\n                }))\n                .build();\n    }\n}\n","sourceCodeStart":487,"sourceCodeEnd":520,"githubUrl":"https://github.com/xpipe-io/xpipe/blob/d85ca821baa46092a320ebb13546d7240adb74f8/app/src/main/java/io/xpipe/app/beacon/mcp/McpTools.java#L487-L520","documentation":"Thrown by the connection state toggle MCP tool when the referenced store is not a SingletonSessionStore, i.e. it has no single start/stop session lifecycle. Only toggleable connections (like shell connections with a singleton session) support switching state on/off.","triggerScenarios":"Calling the toggle tool with a 'system' argument whose resolved data store is a plain data store or a non-session store type (e.g. a simple file store, or a composite/category store).","commonSituations":"Pointing the tool at a non-connection data store, a category/collection instead of an individual connection, or a connection type that is always-on and has no toggleable session.","solutions":["Pass a system reference that resolves to a toggleable connection (SingletonSessionStore)","Check the connection type in XPipe before toggling — use only shell-type connections","Use the connection's UUID or a resolvable store reference rather than a name that may match a category","If the connection is always active, skip the toggle call"],"exampleFix":"// before\ntoggleConnection(system: \"My Home Category\", state: false) // not a store\n// after\ntoggleConnection(system: \"ssh-webserver-uuid\", state: false)","handlingStrategy":"type-guard","validationCode":"function isToggleableConnection(store) {\n  return typeof store === 'object' && store !== null && store.kind === 'singletonSession';\n}\n// only call the toggle tool when the referenced system resolves to a session-backed connection","typeGuard":"function canToggle(systemInfo) {\n  return Boolean(systemInfo && systemInfo.sessionBased === true);\n}","tryCatchPattern":"try {\n  await mcp.call('setConnectionState', {system, state});\n} catch (e) {\n  if (String(e.message) === 'Not a toggleable connection') {\n    // resolve an individual shell connection instead of a category/store\n  }\n}","preventionTips":["Reference individual shell connections, not categories or plain data stores","Inspect the connection type before toggling","Skip toggling for always-on connection types"],"tags":["mcp","connection","validation"],"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"}