t8y2/dbx · error

agentSessionId is required

Error message

agentSessionId is required

What it means

The Cassandra driver agent's dispatch handler requires an agentSessionId parameter for the open_session method. If the params lack a non-empty 'agentSessionId' string, it returns this error instead of opening a session. The ID links subsequent operations to the created gocql session.

Source

Thrown at agents/drivers/cassandra-go/main.go:176

	}
	if len(req.ID) == 0 {
		req.ID = json.RawMessage("1")
	}
	result, shutdown, err := r.dispatch(req.Method, req.Params)
	if err != nil {
		return errorResponse(req.ID, req.Method, stringParam(req.Params, "agentSessionId"), err), false
	}
	return response{JSONRPC: "2.0", ID: req.ID, Result: result}, shutdown
}

func (r *runtimeServer) dispatch(method string, params map[string]json.RawMessage) (any, bool, error) {
	switch method {
	case "handshake":
		return handshakeResult(true), false, nil
	case "open_session":
		id := stringParam(params, "agentSessionId")
		if id == "" {
			return nil, false, errors.New("agentSessionId is required")
		}
		var cp connectParams
		if err := decodeParams(params, &cp); err != nil {
			return nil, false, err
		}
		return map[string]bool{"ok": true}, false, r.openSession(id, cp)
	case "close_session":
		return map[string]bool{"ok": true}, false, r.closeSession(stringParam(params, "agentSessionId"))
	case "validate_session":
		session, err := r.session(stringParam(params, "agentSessionId"))
		if err != nil {
			return nil, false, err
		}
		session.mu.Lock()
		defer session.mu.Unlock()
		return map[string]bool{"ok": true}, false, session.server.validateConnection()
	case "cancel_session":
		session, err := r.session(stringParam(params, "agentSessionId"))

View on GitHub (pinned to c0390bff16)

Solutions

1. Include a non-empty agentSessionId in the open_session params
2. Generate the session ID on the client before dispatch (uuid or similar)
3. Update the client driver to the matching version so it always sends agentSessionId
4. Add an assertion/log in the client that params contains agentSessionId before dispatch

Example fix

// before
// {"method":"open_session","params":{"keyspace":"ks"}}
// after
// {"method":"open_session","params":{"agentSessionId":"4f9c...","keyspace":"ks"}}

function assertOpenSessionParams(params) {
  if (!params || typeof params.agentSessionId !== "string" || params.agentSessionId === "") {
    throw new Error("open_session requires a non-empty agentSessionId");
  }
}

function hasAgentSessionId(p) {
  return typeof p === "object" && p !== null &&
    typeof p.agentSessionId === "string" && p.agentSessionId.length > 0;
}

try { await rpc("open_session", params) }
catch (e) {
  if (e.message.includes("agentSessionId is required")) {
    params.agentSessionId = crypto.randomUUID();
    await rpc("open_session", params);
  }
}

When it happens

Trigger: Sending a JSON-RPC style request with method 'open_session' whose params object omits agentSessionId or passes an empty string.

Common situations: Client SDK version drift where the field was renamed; hand-rolled request payloads in tests or scripts forgetting the field; params serialized with a nil/empty value after failed ID generation upstream.

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

• Key is required
• <label> are required
• agentSessionId is required
• object source is not supported by Cassandra
• execution plans are not supported by Cassandra

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