alibaba/arthas · error · ApiException

'sessionId' is required

Error message

'sessionId' is required

What it means

Thrown when the 'sessionId' field is blank and the action is not EXEC (EXEC is the only action allowed to create an implicit one-time session without a pre-existing sessionId). All other actions (JOIN_SESSION, PULL_RESULTS, INTERRUPT_JOB, CLOSE_SESSION, SESSION_INFO) require an existing session.

Source

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

            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) {
                    throw new ApiException("session not found: " + sessionId);
                }
                sessionManager.updateAccessTime(session);
            }

            // 标记所谓的一次性session
            if (session == null) {
                session = sessionManager.createSession();
                session.put(ONETIME_SESSION_KEY, new Object());
            }

            // 请求到达这里，如果有需要鉴权，则已经在前面的handler里处理过了
            // 如果有鉴权取到的 Subject，则传递到 arthas的session里
            HttpSession httpSession = HttpSessionManager.getHttpSessionFromContext(ctx);

View on GitHub (pinned to 21cf2e9ba5)

Solutions

1. Call INIT_SESSION first and capture the returned sessionId, then include it in all subsequent requests.
2. For EXEC, sessionId is optional (a one-time session is created automatically), but for all other actions it is mandatory.

Example fix

// before: pull_results without sessionId
{"action": "pull_results", "consumerId": "abc"}
// -> 'sessionId' is required

// after
{"action": "pull_results", "sessionId": "<from init_session>", "consumerId": "abc"}

// Client-side: ensure sessionId for non-EXEC actions
if (!"EXEC".equals(action.toUpperCase()) &&
        (sessionId == null || sessionId.trim().isEmpty())) {
    throw new IllegalArgumentException("'sessionId' is required for " + action);
}

boolean needsSessionId(String action) {
    return !"EXEC".equalsIgnoreCase(action);
}

When it happens

Trigger: Calling PULL_RESULTS, JOIN_SESSION, INTERRUPT_JOB, CLOSE_SESSION, or SESSION_INFO without providing a sessionId in the request body.

Common situations: Client forgets to carry the sessionId returned by a prior INIT_SESSION call. Session management logic drops the sessionId between requests.

Related errors

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

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