t8y2/dbx · error

agent session limit reached: %d

Error message

agent session limit reached: %d

What it means

openSession enforces a global cap of maxAgentSessions concurrent registered sessions. When len(r.sessions) already reaches the cap, the new session is refused with 'agent session limit reached: %d', embedding the limit value.

Source

Thrown at agents/drivers/iotdb/main.go:251

		session, err := r.session(id)
		if err != nil {
			return nil, false, err
		}
		session.mu.Lock()
		defer session.mu.Unlock()
		return session.server.dispatch(method, params)
	}
}

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

	server, err := newServer(params)
	if err != nil {
		return err
	}
	if err := server.validateConnection(); err != nil {
		server.disconnect()
		return err
	}

	r.mu.Lock()
	defer r.mu.Unlock()
	if _, exists := r.sessions[id]; exists {
		server.disconnect()
		return fmt.Errorf("agent session already exists: %s", id)
	}

View on GitHub (pinned to c0390bff16)

Solutions

1. Close idle/finished sessions with closeSession to free slots.
2. Increase maxAgentSessions to match expected concurrency.
3. Add client-side cleanup (defer disconnect) so sessions don't leak on errors.
4. Monitor active session count and alert before hitting the cap.

Example fix

// before
rt.openSession(id, params) // never closed
// after
if err := rt.openSession(id, params); err != nil { return err }
defer rt.closeSession(id)

var err error
for i := 0; i < 3; i++ {
    err = rt.openSession(id, params)
    if err == nil || !strings.Contains(err.Error(), "agent session limit reached") {
        break
    }
    time.Sleep(time.Duration(1<<i) * time.Second) // wait for slots to free
}

When it happens

Trigger: Opening an agent session when maxAgentSessions sessions are already registered; sessions leaking because clients never call closeSession/disconnect until the cap is hit.

Common situations: Long-running deployments where clients disconnect abruptly without cleanup; load tests opening hundreds of connections; maxAgentSessions tuned too low for expected concurrency.

Related errors

• Hive Agent session already exists: %s
• Hive Agent session not found: %s
• Agent session already exists: %s
• Agent session limit reached: %d
• Agent session not found: %s

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