t8y2/dbx · error · IllegalArgumentException

agentSessionId is required

Error message

agentSessionId is required

What it means

requiredSessionId extracts agentSessionId from the request params and throws IllegalArgumentException if the field is absent or blank (after trim). Multi-session requests are mandatory-scoped to a session, so a missing ID cannot be routed.

Source

Thrown at agents/common/src/main/java/com/dbx/agent/MultiSessionJsonRpcServer.java:372

        private final int maximumRequestThreads;
        private final int maximumCleanupThreads;

        RuntimeLimits(int maximumRequestThreads, int maximumCleanupThreads) {
            if (maximumRequestThreads <= 0 || maximumCleanupThreads <= 0) {
                throw new IllegalArgumentException("Agent runtime thread limits must be positive");
            }
            this.maximumRequestThreads = maximumRequestThreads;
            this.maximumCleanupThreads = maximumCleanupThreads;
        }

        private static RuntimeLimits defaults() {
            return new RuntimeLimits(MAX_REQUEST_THREADS, MAX_CLEANUP_THREADS);
        }
    }

    private static String requiredSessionId(JsonObject params) {
        if (!params.has("agentSessionId") || params.get("agentSessionId").getAsString().trim().isEmpty()) {
            throw new IllegalArgumentException("agentSessionId is required");
        }
        return params.get("agentSessionId").getAsString();
    }

    private void writeResponse(JsonObject response) {
        synchronized (outputLock) {
            protocolOutput.println(gson.toJson(response));
            protocolOutput.flush();
        }
    }

    private static final class Session {
        private final JsonRpcServer server;
        private final SessionRpcHandler handler;
        private final ReentrantLock lock = new ReentrantLock();
        private final AtomicReference<State> state = new AtomicReference<>(State.ACTIVE);
        private final AtomicBoolean cleanupScheduled = new AtomicBoolean();

View on GitHub (pinned to c0390bff16)

Solutions

1. Include a non-blank agentSessionId in every request's params object
2. Fix the field name to exactly agentSessionId in the client payload
3. Open a session first and thread its ID through all subsequent calls
4. Client-side: validate the params object before sending

Example fix

// before
params.addProperty("sessionId", id);
// after
params.addProperty("agentSessionId", id); // correct key, non-blank

if (!params.has("agentSessionId") || params.get("agentSessionId").getAsString().isBlank()) {
    throw new IllegalArgumentException("agentSessionId must be set before calling the server");
}

boolean hasSessionId(JsonObject p) {
    return p != null && p.has("agentSessionId") && !p.get("agentSessionId").getAsString().trim().isEmpty();
}

When it happens

Trigger: Any multi-session JSON-RPC request whose params omit agentSessionId or pass whitespace/empty string; clients built for single-session mode not sending the field after switching to the multi-session server.

Common situations: Older client versions predating multi-session support; params assembled incorrectly (field name typo like sessionId); null/empty values serialized by generic JSON builders.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Query session not found: {sessionId}
• Agent session already exists: {sessionId}
• Agent session not found: {sessionId}
• Connection failed
• Connection is not valid

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/10bac89316cfadf5. Report an issue: GitHub.