t8y2/dbx · error

agentSessionId is required

Error message

agentSessionId is required

What it means

The Neo4j driver agent's dispatch handles the open_session JSON-RPC method. Multi-session protocol requires each session to be keyed by an agentSessionId; if the params omit it or it is an empty string, dispatch rejects the call before creating a session.

Source

Thrown at agents/drivers/neo4j-go/main.go:204

	}
	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(), false, nil
	case "open_session":
		id := stringParam(params, "agentSessionId")
		if id == "" {
			return nil, false, errors.New("agentSessionId is required")
		}
		var connection connectParams
		if err := decodeParams(params, &connection); err != nil {
			return nil, false, err
		}
		return map[string]bool{"ok": true}, false, r.openSession(id, connection)
	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 (e.g. a UUID) in the open_session params.
2. Upgrade the client library to one speaking the multi-session protocol version.
3. Log the outgoing params JSON to confirm the field name and value; watch for omitempty stripping it.

Example fix

// before
params := map[string]any{"uri": uri} // missing agentSessionId
// after
params := map[string]any{"agentSessionId": sessionId, "uri": uri}

if sessionID == "" {
    return errors.New("cannot open_session: agentSessionId is empty")
}

if _, err := dispatch("open_session", params); err != nil {
    if strings.Contains(err.Error(), "agentSessionId is required") {
        return fmt.Errorf("client bug: generate a session id before open_session: %w", err)
    }
    return err
}

When it happens

Trigger: Sending an open_session request whose params lack the agentSessionId field, or pass agentSessionId: "".

Common situations: Client SDK version predating the multi-session protocol (pre-agentSessionId), hand-rolled JSON payloads missing the field, serialization dropping empty strings via omitempty on the caller side.

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

• agentSessionId is required
• agent session already exists: %s
• unknown method: %s
• Cassandra connection runtime is closed
• agentSessionId is required

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