t8y2/dbx · error · java.lang.IllegalArgumentException

agentSessionId is required

Error message

agentSessionId is required

What it means

MongoAgent's JSON-RPC handlers require an "agentSessionId" string parameter to route calls to the correct open session. requiredSessionId throws IllegalArgumentException when the parameter is missing, null, or blank/whitespace. This is an input-validation guard so session-scoped operations never run against an undefined session.

Source

Thrown at agents/drivers/mongodb/src/main/java/com/dbx/agent/mongodb/MongoAgent.java:2049

        }

        private Session session(String sessionId) {
            Session session = sessions.get(sessionId);
            if (session == null) {
                throw new IllegalStateException("Agent session not found: " + sessionId);
            }
            return session;
        }

        private void closeAllSessions() {
            for (String sessionId : sessions.keySet()) {
                closeSession(sessionId);
            }
        }

        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(String response) {
            synchronized (outputLock) {
                System.out.println(response);
                System.out.flush();
            }
        }
    }

    private static final class Session {
        private final MongoClient client;

        private Session(MongoClient client) {
            this.client = client;
        }

View on GitHub (pinned to c0390bff16)

Solutions

1. Add a non-empty "agentSessionId" string to the request params (use the id returned when the session was opened).
2. If the client drops null/empty fields during serialization, fix the serializer to send the value or re-open a session to obtain a valid id.
3. Wrap the JSON-RPC call in a try-catch for IllegalArgumentException and re-open a session before retrying.

Example fix

// before
client.call("mongo.query", Map.of("database", "shop"));
// after
client.call("mongo.query", Map.of("agentSessionId", sessionId, "database", "shop"));

if (params == null || params.get("agentSessionId") == null || params.get("agentSessionId").isJsonNull() || params.get("agentSessionId").getAsString().trim().isEmpty()) {
    throw new IllegalArgumentException("agentSessionId is required");
}

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

try {
    result = client.call(method, params);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("agentSessionId")) {
        sessionId = openSession(); // re-open and retry once with a valid id
        params.addProperty("agentSessionId", sessionId);
        result = client.call(method, params);
    } else throw e;
}

When it happens

Trigger: Calling any session-scoped MongoAgent JSON-RPC method whose params object omits "agentSessionId", sets it to null, or passes an empty/whitespace-only string (e.g. after closeSession was called with a stale id and the client forgot to re-attach the new id).

Common situations: Client code caches session state and sends stale or empty ids after reconnecting; hand-written JSON-RPC requests in curl/tests omit the field; a serialization layer drops null fields so the key never reaches the agent; copying example payloads that use a different session field name.

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

• <label> are required
• MongoDB aggregate option ${key} must be a non-negative integ
• MongoDB explain verbosity must be queryPlanner, executionSta
• Unsupported findOne option: ${key}
• Unsupported collation option: ${key}

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