t8y2/dbx · error

agentSessionId is required

Error message

agentSessionId is required

What it means

The xugu agent's open_session RPC handler requires the agentSessionId parameter and returns this error when it is missing or empty (stringParam trims/returns empty). Without a session ID the agent cannot register the multi-session connection.

Source

Thrown at agents/drivers/xugu/main.go:786

	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 map[string]any{
			"protocolVersion":      multiSessionProtocolVersion,
			"agentProtocolVersion": multiSessionProtocolVersion,
			"capabilities":         []string{"connect", "test_connection", "metadata", "query", "ddl", "structured_error_v1", "multi_session"},
		}, false, nil
	case "open_session":
		agentSessionID := stringParam(params, "agentSessionId")
		if agentSessionID == "" {
			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(agentSessionID, cp)
	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.validateConnection(); err == nil {
			return map[string]bool{"ok": true}, false, nil

View on GitHub (pinned to c0390bff16)

Solutions

1. Include a non-empty agentSessionId in the open_session params
2. Upgrade the client to the protocol version advertising multi_session so the field is always set
3. Check decodeParams/param marshalling on the client if the field is present but arrives empty

Example fix

// before
params := map[string]any{"connectParams": cp}
// after
params := map[string]any{"agentSessionId": sessionID, "connectParams": cp}

if strings.TrimSpace(agentSessionID) == "" { return errors.New("agentSessionId is required") }

func hasSessionID(params map[string]any) bool { s, _ := params["agentSessionId"].(string); return strings.TrimSpace(s) != "" }

resp, err := agent.RPC(ctx, "open_session", params)
if err != nil && strings.Contains(err.Error(), "agentSessionId is required") { return ErrSessionIDMissing }

When it happens

Trigger: Calling the open_session RPC without params["agentSessionId"], or with an empty/whitespace value; a client using structured_error/multi_session capabilities but omitting the session ID field.

Common situations: Older client versions that predate the multi_session protocol sending open_session without the field; a serialization bug dropping the parameter; manual RPC testing against the agent.

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

• table is required
• lease, ttl, and preserveLease cannot be specified together
• ttl must be a positive integer
• ETCD_WATCH_SCOPE_INVALID
• statements are required

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