alibaba/arthas · error · IllegalArgumentException

vmtool: action 参数不能为空

Error message

vmtool: action 参数不能为空

What it means

The vmtool MCP tool requires a non-null, non-blank action parameter to identify the operation type (getInstances, forceGc, interruptThread, referenceAnalyze). This is the first validation gate before any command construction begins.

Source

Thrown at core/src/main/java/com/taobao/arthas/core/mcp/tool/function/jvm300/VMToolTool.java:48

            @ToolParam(description = "返回实例限制数量 (-l)，getInstances 时使用，默认 10；<=0 表示不限制", required = false)
            Integer limit,

            @ToolParam(description = "结果对象展开层次 (-x)，默认 1", required = false)
            Integer expandLevel,

            @ToolParam(description = "OGNL 表达式，对 getInstances 返回的 instances 执行 (--express)", required = false)
            String express,

            @ToolParam(description = "线程 ID (-t)，interruptThread 时使用", required = false)
            Long threadId,

            ToolContext toolContext
    ) {
        StringBuilder cmd = buildCommand("vmtool");

        if (action == null || action.trim().isEmpty()) {
            throw new IllegalArgumentException("vmtool: action 参数不能为空");
        }
        String normalizedAction = action.trim();
        cmd.append(" --action ").append(normalizedAction);

        if (classLoaderHash != null && !classLoaderHash.trim().isEmpty()) {
            addParameter(cmd, "-c", classLoaderHash);
        } else if (classLoaderClass != null && !classLoaderClass.trim().isEmpty()) {
            addParameter(cmd, "--classLoaderClass", classLoaderClass);
        }

        if (ACTION_GET_INSTANCES.equals(normalizedAction) || ACTION_REFERENCE_ANALYZE.equals(normalizedAction)) {
            if (className == null || className.trim().isEmpty()) {
                throw new IllegalArgumentException("vmtool " + normalizedAction + " 需要指定类名 (className)");
            }
            addParameter(cmd, "--className", className);
        }

        if (ACTION_GET_INSTANCES.equals(normalizedAction)) {

View on GitHub (pinned to 21cf2e9ba5)

Solutions

1. Provide a valid action value: getInstances, forceGc, interruptThread, or referenceAnalyze.
2. Verify the MCP client includes the action field with the correct key name.
3. Check that the action string is not just whitespace.

Example fix

// before
vmtool(action=null)
// after
vmtool(action="getInstances", className="java.lang.String")

// Before calling vmtool, validate action
if (action == null || action.trim().isEmpty()) {
    throw new IllegalArgumentException("action is required for vmtool");
}
Set<String> validActions = Set.of("getInstances", "forceGc", "interruptThread", "referenceAnalyze");
if (!validActions.contains(action.trim())) {
    throw new IllegalArgumentException("Invalid vmtool action: " + action);
}

try {
    String result = vmtool(action, classLoaderHash, ...);
} catch (IllegalArgumentException e) {
    // action was null/empty/invalid — fix the caller to always send action
}

When it happens

Trigger: Calling the vmtool tool with action omitted, null, empty string, or whitespace-only value. The action parameter is declared required (no required=false annotation).

Common situations: MCP client omits the action field in the tool call; JSON serialization drops a null or empty field; field name typo (e.g., 'Action' instead of 'action').

Related errors

• vmtool ${normalizedAction} 需要指定类名 (className)
• vmtool interruptThread 需要指定线程 ID (threadId)
• actionArg is required when action=execute
• action is required
• classPattern is required for record operation

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