t8y2/dbx · error

agent session limit reached: %d

Error message

agent session limit reached: %d

What it means

openSession caps the number of concurrent agent sessions at maxAgentSessions. When the number of live sessions has reached that limit, new sessions are rejected with this error until existing ones are closed. The check happens while holding r.mu, so it is a reliable upper bound.

Source

Thrown at agents/drivers/cassandra-go/main.go:246

		defer session.mu.Unlock()
		release, err := session.server.runtime.acquire(isMetadataOperation(method))
		if err != nil {
			return nil, false, err
		}
		defer release()
		return session.server.dispatch(method, params)
	}
}

func (r *runtimeServer) openSession(id string, cp 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()

	runtime, key, err := r.acquireRuntime(cp)
	if err != nil {
		return err
	}
	s := newServer(runtime, cp)
	if err := s.validateConnection(); err != nil {
		r.releaseRuntime(key)
		return err
	}

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

View on GitHub (pinned to c0390bff16)

Solutions

1. Close idle/finished sessions via the disconnect/close RPC to free capacity, then retry.
2. Add a retry with backoff waiting for session slots to free up.
3. Audit the client for leaked sessions (connect without close on error paths).
4. Raise maxAgentSessions if the workload legitimately requires more concurrent sessions.

Example fix

// before
defers: connect(...) // error paths never call disconnect
// after
resp, err := connect(id)
if err != nil { return err }
defer disconnect(id)

if activeSessions() >= maxAgentSessionsKnownByServer {
    closeIdleSessions()
}

if strings.Contains(err.Error(), "agent session limit reached") {
    time.Sleep(backoff)
    return retryConnect()
}

When it happens

Trigger: openSession called when len(r.sessions) >= maxAgentSessions — i.e. the maximum number of concurrent sessions is already open and none has been closed.

Common situations: Long-lived sessions leaked by clients that never call close/disconnect; a burst of connects from scaled-out workers; automated tests opening sessions without cleanup in teardown.

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