t8y2/dbx · error

agentSessionId is required

Error message

agentSessionId is required

What it means

The dispatcher (dispatch in main.go) routes the open_session method; it requires a non-empty agentSessionId. requiredSessionID extracts the value, and if the resulting string is empty, dispatch returns "agentSessionId is required" before r.openSession is ever called. It is a session-lifecycle protocol validation error.

Source

Thrown at agents/drivers/etcd-go/main.go:205

	}
	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 := requiredSessionID(params)
		if id == "" {
			return nil, false, errors.New("agentSessionId is required")
		}
		return r.openSession(id, params)
	case "close_session":
		return r.closeSession(stringParam(params, "agentSessionId")), false, nil
	case "validate_session":
		session, err := r.session(requiredSessionID(params))
		if err != nil {
			return nil, false, err
		}
		session.mu.Lock()
		defer session.mu.Unlock()
		result, err := session.state.validateConnection()
		return result, false, err
	case "cancel_session":
		session, err := r.session(requiredSessionID(params))
		if err != nil {
			return nil, false, err
		}

View on GitHub (pinned to c0390bff16)

Solutions

1. Always include a non-empty "agentSessionId" string in open_session params.
2. Generate the session ID client-side (UUID/ULID) before dispatching open_session.
3. Fix param-building code so the field name matches "agentSessionId" exactly (case-sensitive).

Example fix

// before
{"method": "open_session", "params": {}}

// after
{"method": "open_session", "params": {"agentSessionId": "6f1c..."}}

if sessionID == "" {
    return errors.New("cannot open_session: agentSessionId is empty; generate a UUID first")
}

func validSessionID(v any) (string, bool) {
    s, ok := v.(string)
    return s, ok && s != ""
}

When it happens

Trigger: Sending an open_session request whose params omit agentSessionId, or contain an empty string ("") — detected at main.go:205 in the dispatch switch.

Common situations: Client SDK misconfiguration where the session ID is generated lazily and not set before open_session; JSON params using the wrong field name; templates/tests that build open_session payloads without the ID.

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
• user is required
• Key is required
• ETCD_DEFRAG_TARGET_REQUIRED
• ETCD_NEWKEY_REQUIRED

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