t8y2/dbx · error

Agent session limit reached: %d

Error message

Agent session limit reached: %d

What it means

openSession enforces maxAgentSessions: once the number of live sessions reaches the cap, new opens are rejected with this error. It is a deliberate resource guard so the runtime server cannot accumulate unbounded etcd2 sessions.

Source

Thrown at agents/drivers/etcd2-go/main.go:234

		defer session.mu.Unlock()
		result, err := session.state.handle(method, params)
		return result, false, err
	}
}

func requiredSessionID(params map[string]json.RawMessage) string {
	return strings.TrimSpace(stringParam(params, "agentSessionId"))
}

func (r *runtimeServer) openSession(id string, params map[string]json.RawMessage) (any, bool, error) {
	r.mu.Lock()
	if _, exists := r.sessions[id]; exists {
		r.mu.Unlock()
		return nil, false, fmt.Errorf("Agent session already exists: %s", id)
	}
	if len(r.sessions) >= maxAgentSessions {
		r.mu.Unlock()
		return nil, false, fmt.Errorf("Agent session limit reached: %d", maxAgentSessions)
	}
	session := &agentSession{state: newEtcd2Session()}
	r.sessions[id] = session
	r.mu.Unlock()

	if _, err := session.state.connect(params); err != nil {
		r.mu.Lock()
		delete(r.sessions, id)
		r.mu.Unlock()
		session.state.close()
		return nil, false, err
	}
	return map[string]bool{"ok": true}, false, nil
}

func (r *runtimeServer) session(id string) (*agentSession, error) {
	r.mu.RLock()
	session := r.sessions[id]

View on GitHub (pinned to c0390bff16)

Solutions

1. Close idle/finished sessions with closeSession before opening new ones.
2. Increase maxAgentSessions if the workload legitimately needs more concurrent sessions.
3. Add leak detection in callers: ensure every openSession has a matching close in a finally/defer path.

Example fix

// before
openSession(id, params) // cap reached, throws
// after
for _, old := range staleSessionIDs { closeSession(old) }
openSession(id, params)

session, err := openSession(id, params)
if err != nil && strings.Contains(err.Error(), "limit reached") {
    evictOldestSession()
    session, err = openSession(id, params)
}

When it happens

Trigger: Opening a new session when len(r.sessions) >= maxAgentSessions — typically after many sessions were opened without being closed, or in a test suite that opens sessions per test.

Common situations: Long-running agents leaking sessions on error paths, load tests hitting the cap, raising concurrency without raising the limit.

Related errors

• agent session limit reached: %d
• agent session limit reached: %d
• agent session limit reached: %d
• MongoDB aggregate limit must be between 0 and ${Integer.MAX_
• agentSessionId is required

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