alibaba/arthas · error · IllegalArgumentException

Required parameter '{}' is missing

Error message

Required parameter '{}' is missing

What it means

Thrown by DefaultToolCallback.validateRequiredParameters() when invoking a @Tool method whose parameter is annotated @ToolParam(required = true) and the corresponding argument is null (absent from the tool input). It is an IllegalArgumentException thrown synchronously during tool dispatch, before the method body runs. A separate guard rejects empty/blank strings with 'cannot be empty'.

Source

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

    /**
     * validate the required parameters
     */
    private void validateRequiredParameters(Map<String, Object> toolArguments) {
        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;

View on GitHub (pinned to 21cf2e9ba5)

Solutions

  1. Ensure the MCP client sends all parameters marked @ToolParam(required = true) with non-null values.
  2. Compile with the -parameters javac flag so parameter names resolve correctly and match the argument keys.
  3. Mark the parameter optional (required = false) if it is genuinely optional, or supply a default in the method.
  4. Align the tool's input JSON schema with the @ToolParam annotations so clients know required fields.

Example fix

// before
public String run(@ToolParam(required = true) String path) { ... }
// compiled without -parameters -> paramName == "arg0", client sends "path"

// after (javac)
<plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration><parameters>true</parameters></configuration>
</plugin>
// and ensure the client includes {"path": "/some/value"}
Defensive patterns

Strategy: validation

Validate before calling

// Client-side: ensure all required @ToolParam fields are present and non-null
Map<String,Object> args = new HashMap<>();
args.put("path", Objects.requireNonNull(path));
// verify no required key is null before invoking the tool
for (String req : requiredParams) {
    if (args.get(req) == null) throw new IllegalArgumentException("missing " + req);
}

Type guard

// Guard that a required argument is a non-blank string
static boolean isPresentString(Map<String,Object> args, String key) {
    Object v = args.get(key);
    return v != null && (!(v instanceof String s) || !s.trim().isEmpty());
}

Try / catch

try {
    toolCallback.call(toolInput);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("is missing") || e.getMessage().contains("cannot be empty")) {
        // report the missing/empty required param back to the client
        return errorResponse(e.getMessage());
    }
    throw e;
}

Prevention

When it happens

Trigger: An MCP client calls the tool without supplying a parameter declared @ToolParam(required = true); the JSON arguments map lacks that key; the key name does not match the Java parameter name (e.g. -parameters compiler flag missing so parameter.getName() returns 'arg0').

Common situations: Client omitting a required field; parameter name mismatch due to compiling without the -parameters flag (so paramName becomes 'arg0' and never matches the client's key); schema/client drift on required fields.

Related errors

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