What causes "actionArg is required when action=execute" in alibaba/arthas?

Provide actionArg with valid async-profiler agent arguments, e.g. "start,event=cpu" or "stop,file=/tmp/result.html".

alibaba/arthas · error · IllegalArgumentException

actionArg is required when action=execute

Error message

actionArg is required when action=execute

What it means

The profiler execute action passes raw arguments directly to the async-profiler agent via actionArg. Because execute bypasses the structured option mapping, actionArg is the sole carrier of the command and must not be empty.

Source

Thrown at core/src/main/java/com/taobao/arthas/core/mcp/tool/function/monitor200/ProfilerTool.java:161

            String timeout,

            @ToolParam(description = "持续采样秒数 (--duration)。注意：到时自动 stop 在后台执行，stop 的结果不会回传到当前命令输出。", required = false)
            Long duration,

            @ToolParam(description = "启用的特性集合 (--features)", required = false)
            String features,

            @ToolParam(description = "采样信号 (--signal)", required = false)
            String signal,

            @ToolParam(description = "时间戳时钟源 (--clock)，可选 monotonic 或 tsc", required = false)
            String clock,

            ToolContext toolContext
    ) {
        String normalizedAction = normalizeAction(action);
        if ("execute".equals(normalizedAction) && (actionArg == null || actionArg.trim().isEmpty())) {
            throw new IllegalArgumentException("actionArg is required when action=execute");
        }

        StringBuilder cmd = buildCommand("profiler");
        cmd.append(" ").append(normalizedAction);

        if (actionArg != null && !actionArg.trim().isEmpty()) {
            addParameter(cmd, actionArg);
        }

        // profiler options
        addOption(cmd, "--event", event);
        addOption(cmd, "--alloc", alloc);
        addFlag(cmd, "--live", live);
        addOption(cmd, "--lock", lock);
        addOption(cmd, "--jfrsync", jfrsync);

        addOption(cmd, "--file", file);
        addOption(cmd, "--format", format);

View on GitHub (pinned to 21cf2e9ba5)

Solutions

Provide actionArg with valid async-profiler agent arguments, e.g. "start,event=cpu" or "stop,file=/tmp/result.html".
For common use cases prefer action=start with structured options (event, file, format) instead of action=execute.
Check that actionArg is not whitespace-only.

Example fix

// before
profiler(action="execute")
// after
profiler(action="execute", actionArg="start,event=cpu")
// or simpler: use structured action
profiler(action="start", event="cpu")

Defensive patterns

Strategy: validation

Validate before calling

// Before calling profiler execute, validate actionArg
if ("execute".equalsIgnoreCase(action)
        && (actionArg == null || actionArg.trim().isEmpty())) {
    throw new IllegalArgumentException("actionArg is required when action=execute");
}

Try / catch

try {
    String result = profiler(action, actionArg, ...);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("actionArg")) {
        // actionArg missing for execute — switch to structured action=start or provide args
    }
}

Prevention

Prefer structured actions (start, stop) over execute for common profiling scenarios.
If using execute, always include the full async-profiler agent argument string.
Validate actionArg client-side when action is execute.

When it happens

Trigger: Calling the profiler tool with action=execute but omitting actionArg or passing a blank value. The check at line 160 runs immediately after normalizeAction succeeds.

Common situations: User confuses execute with start (which uses structured options, not actionArg); forgets to include the agent arguments string; assumes execute infers defaults.

Related errors

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