alibaba/arthas · error · ApiException

unknown action: {}

Error message

unknown action: {}

What it means

Thrown when ApiAction.valueOf() fails because the provided action string (uppercased and trimmed) does not match any ApiAction enum constant. Valid actions are: EXEC, ASYNC_EXEC, INTERRUPT_JOB, PULL_RESULTS, INIT_SESSION, JOIN_SESSION, CLOSE_SESSION, SESSION_INFO.

Source

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

            //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)) {
                if (!allowNullSession) {
                    throw new ApiException("'sessionId' is required");
                }
            } else {
                session = sessionManager.getSession(sessionId);
                if (session == null) {

View on GitHub (pinned to 21cf2e9ba5)

Solutions

1. Use one of the valid action values: EXEC, ASYNC_EXEC, INTERRUPT_JOB, PULL_RESULTS, INIT_SESSION, JOIN_SESSION, CLOSE_SESSION, SESSION_INFO.
2. Action matching is case-insensitive (uppercased internally) but spelling must be exact.
3. Check the Arthas version — older versions may not support all actions.

Example fix

// before
{"action": "execute", "command": "version"}
// -> unknown action: execute

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

// Client-side: validate action against known enum values
Set<String> valid = EnumSet.allOf(ApiAction.class).stream()
    .map(Enum::name).collect(Collectors.toSet());
if (!valid.contains(req.getAction().trim().toUpperCase())) {
    throw new IllegalArgumentException(
        "Invalid action. Valid: " + valid);
}

boolean isValidAction(String action) {
    try {
        ApiAction.valueOf(action.trim().toUpperCase());
        return true;
    } catch (IllegalArgumentException e) {
        return false;
    }
}

When it happens

Trigger: The action field contains a typo (e.g. 'execute' instead of 'exec'), a deprecated action name, or an entirely fabricated value that is not part of the enum.

Common situations: Using the wrong action vocabulary (e.g. 'run' instead of 'exec'). Version mismatch where a client targets actions that don't exist in the deployed Arthas version.

Related errors

• 'action' is required
• parse request failed: request body is empty
• parse request failed: {}
• 'sessionId' is required
• session not found: {}

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