t8y2/dbx · error

agent session limit reached: %d

Error message

agent session limit reached: %d

What it means

The runtime server caps concurrent agent sessions at maxAgentSessions. openSession checks len(r.sessions) before acquiring a runtime and returns this error when the registry is full, protecting the process from unbounded runtime/memory growth.

Source

Thrown at agents/drivers/neo4j-go/main.go:268

		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()

	runtime, key, err := r.acquireRuntime(params)
	if err != nil {
		return err
	}
	server := newServer(runtime, params)
	if err := server.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 sessions (closeSession/disconnect) to free slots
2. Raise maxAgentSessions if the host can support more concurrent runtimes
3. Reuse existing sessions instead of opening one per request
4. Audit clients for leaked sessions (opened but never disconnected)

Example fix

// before
for _, w := range workers { openSession(fmt.Sprintf("worker-%d", i)) } // one session per query
// after
sess := getOrCreateSharedSession() // reuse one session across queries, close on shutdown

if activeSessionCount() >= maxAgentSessions {
    return fmt.Errorf("client-side guard: would exceed %d agent sessions", maxAgentSessions)
}

err := openSession(id, params)
if err != nil && strings.Contains(err.Error(), "session limit reached") {
    // back off, close an idle session, then retry once
    closeOldestIdleSession()
    err = openSession(id, params)
}
return err

When it happens

Trigger: Calling openSession when maxAgentSessions sessions are already registered. The check runs under r.mu right after the duplicate-id check and before acquireRuntime.

Common situations: Long-lived sessions never closed by clients so the registry fills up; a load test opening many parallel sessions; a leaked-session bug on the client side exhausting the fixed cap.

Related errors

• agent session limit reached: %d
• Agent session limit reached: %d
• agent session limit reached: %d
• agentSessionId is required
• agent session already exists: %s

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