t8y2/dbx · error

agentSessionId is required

Error message

agentSessionId is required

What it means

The runtime server's dispatch handler requires an agentSessionId parameter for the open_session method; if the string parameter is absent or empty, it rejects the request with this error before decoding connection parameters. Each agent-side session must have a caller-supplied identifier so sessions remain isolated in the runtime server.

Source

Thrown at agents/drivers/hive-go/main.go:182

	}
	if len(request.ID) == 0 {
		request.ID = json.RawMessage("1")
	}
	result, shutdown, err := runtimeServer.dispatch(request.Method, request.Params)
	if err != nil {
		return errorResponse(request.ID, request.Method, stringParam(request.Params, "agentSessionId"), err), false
	}
	return response{JSONRPC: "2.0", ID: request.ID, Result: result}, shutdown
}

func (runtimeServer *runtimeServer) dispatch(method string, params map[string]json.RawMessage) (any, bool, error) {
	switch method {
	case "handshake":
		return handshakeResult(true), 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, runtimeServer.openSession(id, connection)
	case "close_session":
		return map[string]bool{"ok": true}, false, runtimeServer.closeSession(stringParam(params, "agentSessionId"))
	case "validate_session":
		session, err := runtimeServer.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 := runtimeServer.session(stringParam(params, "agentSessionId"))

View on GitHub (pinned to c0390bff16)

Solutions

1. Include a non-empty agentSessionId string in the open_session params
2. Regenerate the agentSessionId per logical session before calling open_session
3. Update older client code to the current protocol version that mandates agentSessionId
4. Check the handshake capabilities advertisement to confirm protocol expectations match

Example fix

// before
{"method":"open_session","params":{"host":"hs2:10000"}}
// after
{"method":"open_session","params":{"agentSessionId":"agent-1","host":"hs2:10000"}}

func validateOpenSession(params map[string]any) error {
    id, _ := params["agentSessionId"].(string)
    if strings.TrimSpace(id) == "" {
        return errors.New("open_session requires a non-empty agentSessionId")
    }
    return nil
}
// run before writing the request to the driver's stdin

resp, err := callDriver("open_session", params)
if err != nil && strings.Contains(err.Error(), "agentSessionId is required") {
    return fmt.Errorf("client bug: include agentSessionId in open_session params: %w", err)
}

When it happens

Trigger: Sending a JSON-RPC-style open_session request over the driver's stdin/stdout protocol without params.agentSessionId, or with agentSessionId set to "".

Common situations: Older client implementations written before agentSessionId was mandated, hand-rolled protocol callers omitting the field, or a client reusing an empty ID after a failed session teardown.

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
• Key is required
• agentSessionId is required
• agentSessionId is required
• agentSessionId is required

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