xpipe-io/xpipe · error · BeaconClientException

Modifications to connection ${path} is disabled by the categ

Error message

Modifications to connection ${path} is disabled by the category setting

What it means

McpToolHandler.getShellStoreRef checks the connection category's effective configuration: when the category has the 'don't allow scripts' option enabled (getDontAllowScripts()), any mutation-requesting MCP shell operation throws this BeaconClientException. This is a deliberate policy guard, not a transient failure.

Source

Thrown at app/src/main/java/io/xpipe/app/beacon/mcp/McpToolHandler.java:165

            }

            var e = found.getFirst();
            return e.ref();
        }

        public DataStoreEntryRef<ShellStore> getShellStoreRef(String name, boolean mutation)
                throws BeaconClientException {
            var ref = getDataStoreRef(name);
            var isShell = ref.getStore() instanceof ShellStore;
            if (!isShell) {
                throw new BeaconClientException("Connection "
                        + DataStorage.get().getStorePath(ref.get()).toString() + " is not a shell connection");
            }

            var disableMutation =
                    DataStorage.get().getEffectiveCategoryConfig(ref.get()).getDontAllowScripts();
            if (mutation && disableMutation != null && disableMutation) {
                throw new BeaconClientException("Modifications to connection "
                        + DataStorage.get().getStorePath(ref.get()).toString()
                        + " is disabled by the category setting");
            }

            return ref.asNeeded();
        }
    }
}

View on GitHub (pinned to d85ca821ba)

Solutions

1. Disable the 'don't allow scripts' / disallow modifications setting on the connection's category in the XPipe UI (requires appropriate permissions)
2. Move the connection to a category that allows script mutations
3. Perform the operation manually instead of via MCP, or ask an admin to lift the restriction
4. Catch BeaconClientException and inform the user the connection category forbids mutations

Example fix

// before (category config)
"dontAllowScripts": true
// after
"dontAllowScripts": false // or move connection to a permissive category

// consult category policy before requesting mutation
const cfg = await getCategoryConfig(conn.category);
if (mutationNeeded && cfg.dontAllowScripts) {
  throw new Error(`mutations on '${conn.path}' are blocked by category policy`);
}

try { return shellTool.call({name, mutation: true}); } catch (BeaconClientException e) { if (e.message.includes('disabled by the category setting')) { /* surface policy message; offer non-mutating fallback */ } throw e; }

When it happens

Trigger: Calling an MCP shell tool with mutation=true (state-changing operations) against a connection whose category config has dontAllowScripts set; retrying the same call always fails until the setting changes.

Common situations: Production connection categories locked down by admins to forbid script/automation changes; shared team installs where the category policy was tightened; users unaware the category-level setting overrides per-connection use.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• Missing argument for key " + key
• Invalid argument for key " + key
• No connection found for input " + name
• Multiple connections found: " + connectionPaths
• Connection ${path} is not a shell connection

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