t8y2/dbx · error

agentSessionId is required

Error message

agentSessionId is required

What it means

Same rule as the Neo4j driver: the Oracle driver agent's dispatch for open_session requires a non-empty agentSessionId to key the new session in the runtime's session map. Empty IDs would collide and make later session lookups ambiguous, so the request is rejected.

Source

Thrown at agents/drivers/oracle-go/main.go:674

	result, shouldShutdown, err := r.dispatch(req.Method, req.Params)
	if err != nil {
		return errorResponse(req.ID, err), false
	}
	return response{JSONRPC: "2.0", ID: req.ID, Result: result}, shouldShutdown
}

func (r *runtimeServer) dispatch(method string, params map[string]json.RawMessage) (any, bool, error) {
	switch method {
	case "handshake":
		return map[string]any{
			"protocolVersion":      multiSessionProtocolVersion,
			"agentProtocolVersion": multiSessionProtocolVersion,
			"capabilities":         []string{"connect", "test_connection", "metadata", "query", "transaction", "ddl", "multi_session"},
		}, false, nil
	case "open_session":
		agentSessionID := stringParam(params, "agentSessionId")
		if agentSessionID == "" {
			return nil, false, errors.New("agentSessionId is required")
		}
		var connectParams connectParams
		if err := decodeParams(params, &connectParams); err != nil {
			return nil, false, err
		}
		return map[string]bool{"ok": true}, false, r.openSession(agentSessionID, connectParams)
	case "close_session":
		return map[string]bool{"ok": true}, false, r.closeSession(stringParam(params, "agentSessionId"))
	case "validate_session":
		agentSessionID := stringParam(params, "agentSessionId")
		session, err := r.session(agentSessionID)
		if err != nil {
			return nil, false, err
		}
		session.mu.Lock()
		defer session.mu.Unlock()
		if _, _, err := session.server.dispatch("validate_connection", params); err == nil {
			return map[string]bool{"ok": true}, false, nil

View on GitHub (pinned to c0390bff16)

Solutions

1. Send a non-empty agentSessionId in open_session params.
2. Upgrade/align client protocol with the advertised multi_session capability.
3. Add a client-side check that sessionID != "" before dispatching open_session.

Example fix

// before
{ "method": "open_session", "params": {"dsn": dsn} }
// after
{ "method": "open_session", "params": {"agentSessionId": id, "dsn": dsn} }

if agentSessionID == "" {
    return errors.New("open_session requires a non-empty agentSessionId")
}

resp, err := dispatch("open_session", params)
if err != nil && strings.Contains(err.Error(), "agentSessionId is required") {
    params["agentSessionId"] = uuid.NewString()
    return dispatch("open_session", params)
}

When it happens

Trigger: open_session request params with agentSessionId absent or empty string.

Common situations: Older client not implementing the multi_session capability handshake, template code leaving the session ID blank, JSON marshaling with omitempty dropping an empty value.

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
• Cassandra connection runtime is closed
• agentSessionId is required
• agentSessionId is required

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