t8y2/dbx · error

agentSessionId is required

Error message

agentSessionId is required

What it means

dispatch routes JSON-RPC style methods for the etcd2 agent. open_session requires an agentSessionId to identify the session being created; when requiredSessionID(params) returns an empty string, dispatch fails with this error before any session is opened. Sessions drive subsequent per-key operations, so the ID is mandatory.

Source

Thrown at agents/drivers/etcd2-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(), 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. Pass a non-empty agentSessionId string in the open_session params.
2. Generate a stable session identifier (e.g., UUID) client-side before dispatching open_session.
3. Validate the ID at the transport layer so empty IDs never reach dispatch.
4. Check that your client wrapper copies agentSessionId from the handshake result into subsequent calls.

Example fix

// before
res, err := client.Call(ctx, "open_session", map[string]any{})
// after
sessionID := uuid.NewString()
res, err := client.Call(ctx, "open_session", map[string]any{"agentSessionId": sessionID})

id, _ := params["agentSessionId"].(string)
if id == "" {
    return errors.New("generate a session id before calling open_session")
}

if _, err := client.Call(ctx, "open_session", params); err != nil && strings.Contains(err.Error(), "agentSessionId is required") {
    // create/regenerate the session id and re-dispatch
}

When it happens

Trigger: Calling the open_session method without agentSessionId in params, with agentSessionId: null, or with an empty string value.

Common situations: A client handshake/transport layer that forgets to propagate the session ID generated by the caller; generating the ID asynchronously and dispatching before it is set; a config file or env template where the session-id field was left blank.

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/2fec92f4ee21940d. Report an issue: GitHub.