alibaba/arthas · error · IllegalArgumentException

Required parameter '{paramName}' cannot be empty

Error message

Required parameter '{paramName}' cannot be empty

What it means

DefaultToolCallback inspects each method parameter annotated with @ToolParam(required = true). After resolving the value from toolArguments, if the value is a String whose trimmed form is empty it throws IllegalArgumentException("... cannot be empty"). A null value throws a different message ("is missing"), so this specific error fires only when a non-null but blank string is supplied.

Source

Thrown at arthas-mcp-server/src/main/java/com/taobao/arthas/mcp/server/tool/DefaultToolCallback.java:114

        Parameter[] parameters = this.toolMethod.getParameters();
        
        for (Parameter parameter : parameters) {
            if (parameter.getType().isAssignableFrom(ToolContext.class)) {
                continue;
            }
            
            ToolParam toolParam = parameter.getAnnotation(ToolParam.class);
            if (toolParam != null && toolParam.required()) {
                String paramName = parameter.getName();
                Object paramValue = toolArguments.get(paramName);
                
                // check if the parameter is empty or an empty string
                if (paramValue == null) {
                    throw new IllegalArgumentException("Required parameter '" + paramName + "' is missing");
                }

                if (paramValue instanceof String && ((String) paramValue).trim().isEmpty()) {
                    throw new IllegalArgumentException("Required parameter '" + paramName + "' cannot be empty");
                }
            }
        }
    }

    private Map<String, Object> extractToolArguments(String toolInput) {
        return JsonParser.fromJson(toolInput, new TypeReference<Map<String, Object>>() {
        });
    }

    private Object[] buildMethodArguments(Map<String, Object> toolInputArguments, ToolContext toolContext) {
        return Stream.of(this.toolMethod.getParameters()).map(parameter -> {
            if (parameter.getType().isAssignableFrom(ToolContext.class)) {
                return toolContext;
            }
            Object rawArgument = toolInputArguments.get(parameter.getName());
            return buildTypedArgument(rawArgument, parameter.getParameterizedType());
        }).toArray();

View on GitHub (pinned to 21cf2e9ba5)

Solutions

  1. Supply a non-blank value for the required parameter.
  2. If the parameter is genuinely optional, change @ToolParam(required = false) (or remove required) in the tool method.
  3. Trim and validate required string inputs on the client side before calling the tool.

Example fix

// before
@ToolParam(required = true) String expr;
// caller: tool.call({"expr": ""})  -> throws

// after - validate client-side and send a real value
String e = rawExpr == null ? "" : rawExpr.trim();
if (e.isEmpty()) throw new IllegalArgumentException("expr required");
tool.call(Map.of("expr", e));
Defensive patterns

Strategy: validation

Validate before calling

for (Map.Entry<String,Object> e : toolArguments.entrySet()) {
    Object v = e.getValue();
    if (v instanceof String s && s.trim().isEmpty() && isRequired(e.getKey())) {
        throw new IllegalArgumentException("Required param " + e.getKey() + " is blank");
    }
}

Type guard

static boolean isNonBlankRequired(Object value) {
    return value != null && (!(value instanceof String s) || !s.trim().isEmpty());
}

Try / catch

try {
    callback.call(toolInput);
} catch (IllegalArgumentException e) {
    if (e.getMessage().endsWith("cannot be empty")) {
        // prompt user / return tool-error to client
    } else throw e;
}

Prevention

When it happens

Trigger: Invoking an MCP tool whose method signature has a @ToolParam(required = true) String parameter, passing a tool input JSON like {"paramName": ""} or {"paramName": " "}.

Common situations: Client form sends an empty default string instead of omitting the field; JSON null-vs-empty confusion (null yields "is missing", not this error); whitespace-only input from a trimmed UI field; schema mismatch where the client believes the field is optional.

Related errors

AI-assisted analysis of alibaba/arthas@21cf2e9ba5 (2026-08-14). Data as JSON: /api/errors/64169d8e7616a6cc. Report an issue: GitHub.