xpipe-io/xpipe · error · BeaconClientException

Missing argument for key " + key

Error message

Missing argument for key " + key

What it means

McpToolHandler.getStringArgument requires a string-typed tool argument under the given key. When the MCP tool call request carries no arguments map at all (arguments() == null), no value can be retrieved, so it throws BeaconClientException.

Source

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

            return request;
        }

        public Optional<String> getOptionalStringArgument(String key) {
            var o = request.arguments().get(key);
            if (o == null) {
                return Optional.empty();
            }

            if (!(o instanceof String s) || s.isBlank()) {
                return Optional.empty();
            }

            return Optional.of(s);
        }

        public String getStringArgument(String key) throws BeaconClientException {
            if (request.arguments() == null) {
                throw new BeaconClientException("Missing argument for key " + key);
            }

            var o = request.arguments().get(key);
            if (o == null) {
                throw new BeaconClientException("Missing argument for key " + key);
            }

            if (!(o instanceof String s) || s.isBlank()) {
                throw new BeaconClientException("Invalid argument for key " + key);
            }

            return s;
        }

        public Optional<Boolean> getOptionalBooleanArgument(String key) {
            var o = request.arguments().get(key);
            if (o == null) {
                return Optional.empty();

View on GitHub (pinned to d85ca821ba)

Solutions

1. Include the required key in the tool call's arguments object
2. Use getOptionalStringArgument for optional parameters
3. Client-side: validate required tool input against the tool's inputSchema before invoking
4. Return the tool's input schema requirement in the tool description so clients send it

Example fix

// before
handler.getStringArgument("connection"); // arguments == null
// after
var conn = handler.getOptionalStringArgument("connection").orElseThrow(
    () -> new IllegalArgumentException("'connection' is required"));

if (toolCall.arguments() == null || toolCall.arguments().get("connection") == null) {
    throw new IllegalArgumentException("'connection' argument required");
}

try {
    String v = handler.getStringArgument(key);
} catch (BeaconClientException ex) {
    if (ex.getMessage().contains("Missing argument")) {
        // reply to the MCP client with an input-schema error
    } else throw ex;
}

When it happens

Trigger: An MCP client invoking a tool without sending any 'arguments' object while the tool handler calls getStringArgument for a required parameter.

Common situations: Client omits the arguments object entirely for a no-thought invocation; hand-crafted JSON-RPC calls missing 'arguments'; older MCP clients not sending optional fields.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid argument for key " + key
• Not a shell connection
• Unable to parse store data into valid store
• Category with id " + msg.getCategory() + " does not exist
• No connection found for input " + msg.getConnection()

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