alibaba/arthas · error · ApiException

'action' is required

Error message

'action' is required

What it means

Thrown by HttpApiHandler.processRequest when the 'action' field in the parsed ApiRequest is blank. Every HTTP API request must specify an action telling Arthas what operation to perform (e.g. exec, init_session, pull_results).

Source

Thrown at core/src/main/java/com/taobao/arthas/core/shell/term/impl/http/api/HttpApiHandler.java:121

    private ApiRequest parseRequest(String requestBody) throws ApiException {
        if (StringUtils.isBlank(requestBody)) {
            throw new ApiException("parse request failed: request body is empty");
        }
        try {
            //ObjectMapper objectMapper = new ObjectMapper();
            //return objectMapper.readValue(requestBody, ApiRequest.class);
            return JSON.parseObject(requestBody, ApiRequest.class);
        } catch (Exception e) {
            throw new ApiException("parse request failed: " + e.getMessage(), e);
        }
    }

    private ApiResponse processRequest(ChannelHandlerContext ctx, ApiRequest apiRequest) {

        String actionStr = apiRequest.getAction();
        try {
            if (StringUtils.isBlank(actionStr)) {
                throw new ApiException("'action' is required");
            }
            ApiAction action;
            try {
                action = ApiAction.valueOf(actionStr.trim().toUpperCase());
            } catch (IllegalArgumentException e) {
                throw new ApiException("unknown action: " + actionStr);
            }

            //no session required
            if (ApiAction.INIT_SESSION.equals(action)) {
                return processInitSessionRequest(apiRequest);
            }

            //required session
            Session session = null;
            boolean allowNullSession = ApiAction.EXEC.equals(action);
            String sessionId = apiRequest.getSessionId();
            if (StringUtils.isBlank(sessionId)) {

View on GitHub (pinned to 21cf2e9ba5)

Solutions

1. Include a non-empty 'action' field matching one of: EXEC, ASYNC_EXEC, INTERRUPT_JOB, PULL_RESULTS, INIT_SESSION, JOIN_SESSION, CLOSE_SESSION, SESSION_INFO.
2. Double-check the JSON key is exactly 'action' (case-sensitive).

Example fix

// before
{"command": "version"}
// -> 'action' is required

// after
{"action": "exec", "command": "version"}

// Client-side: verify action is set
if (apiRequest.getAction() == null || apiRequest.getAction().trim().isEmpty()) {
    throw new IllegalArgumentException("'action' is required");
}

boolean hasValidAction(ApiRequest req) {
    String a = req.getAction();
    return a != null && !a.trim().isEmpty();
}

When it happens

Trigger: The JSON body is valid but does not include an 'action' field, or the field is present but empty/null.

Common situations: Client constructs the request object programmatically and forgets to set the action field. JSON uses a different key name (e.g. 'type' instead of 'action').

Related errors

• parse request failed: request body is empty
• unknown action: {}
• 'sessionId' is required
• 'consumerId' is required
• parse request failed: {}

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