t8y2/dbx · error

maximum Hive Agent sessions reached (%d)

Error message

maximum Hive Agent sessions reached (%d)

What it means

The runtime server enforces a hard cap (maxAgentSessions) on concurrent Hive Agent sessions. openSession checks the session count under the lock before creating anything and rejects new sessions once the cap is reached.

Source

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

	sessionID := stringParam(params, "agentSessionId")
	if sessionID == "" {
		sessionID = legacyAgentSessionID
	}
	session, err := runtimeServer.session(sessionID)
	if err != nil {
		return nil, false, err
	}
	session.mu.Lock()
	defer session.mu.Unlock()
	return session.server.dispatch(method, params)
}

func (runtimeServer *runtimeServer) openSession(id string, params connectParams) error {
	runtimeServer.mu.Lock()
	if len(runtimeServer.sessions) >= maxAgentSessions {
		runtimeServer.mu.Unlock()
		return fmt.Errorf("maximum Hive Agent sessions reached (%d)", maxAgentSessions)
	}
	if _, exists := runtimeServer.sessions[id]; exists {
		runtimeServer.mu.Unlock()
		return fmt.Errorf("Hive Agent session already exists: %s", id)
	}
	runtimeServer.mu.Unlock()

	server, err := newServer(params)
	if err != nil {
		return err
	}
	runtimeServer.mu.Lock()
	defer runtimeServer.mu.Unlock()
	if _, exists := runtimeServer.sessions[id]; exists {
		_ = server.disconnect()
		return fmt.Errorf("Hive Agent session already exists: %s", id)
	}
	if len(runtimeServer.sessions) >= maxAgentSessions {

View on GitHub (pinned to c0390bff16)

Solutions

1. Close idle/finished sessions with closeSession so slots free up.
2. Raise maxAgentSessions in the runtime configuration to match expected concurrency.
3. Fix client code to close sessions deterministically (defer close / lifecycle hooks) instead of leaking them.
4. Check for replaceSession flows accidentally creating new sessions instead of replacing.

if err := rt.openSession(id, params); err != nil {
    if strings.Contains(err.Error(), "maximum Hive Agent sessions reached") {
        // free a slot then retry
        rt.closeSession(oldestSessionID())
        err = rt.openSession(id, params)
    }
    if err != nil { return err }
}

When it happens

Trigger: Calling openSession (via dispatch of a new-session request, or replaceSession) when len(runtimeServer.sessions) >= maxAgentSessions.

Common situations: Clients leaking sessions (never closing them), many concurrent agents sharing one runtime process, an undersized maxAgentSessions setting for the workload.

Related errors

• agent session limit reached
• %w: %d
• published HiveServer2 configuration has no valid host and po
• Hive driver does not expose HiveServer2 metadata RPCs
• agent operation capacity is temporarily exhausted

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