t8y2/dbx · error

agent session limit reached

Error message

agent session limit reached

What it means

errAgentSessionLimit is a sentinel error thrown when the agent registry has reached maxAgentSessions and cannot register another session. Callers wrap it with the current limit using %w, so errors.Is can detect it. classifyRPCError maps it into a structured error response with retryable=false.

Source

Thrown at agents/drivers/xugu/protocol_error.go:17

package main

import (
	"context"
	"database/sql"
	"database/sql/driver"
	"errors"
	"fmt"
	"io"
	"net"
	"regexp"
	"strconv"
	"strings"
)

var (
	errAgentSessionLimit     = errors.New("agent session limit reached")
	errAgentSessionNotFound  = errors.New("agent session not found")
	errXuguOperationTimeout  = errors.New("xugu operation timed out")
	errXuguOperationCanceled = errors.New("xugu operation canceled")

	// go-xugu-driver exposes server errors as plain strings rather than a typed
	// error. Match only the stable server error header and keep the complete
	// original message for diagnostics. A response can contain more than one
	// Xugu error; vendorCode intentionally records the first/top-level code.
	xuguServerErrorHeader = regexp.MustCompile(`(?im)^[\t ]*(?:error:[\t ]*)?\[[\t ]*E([0-9]{1,9})(?:[\t ]+L([0-9]+))?(?:[\t ]+C([0-9]+))?[\t ]*\]`)
	xuguQueryTimeout      = regexp.MustCompile(`(?i)^query timed out after [1-9][0-9]*s$`)
)

type rpcError struct {
	Code    int           `json:"code"`
	Message string        `json:"message"`
	Data    *rpcErrorData `json:"data,omitempty"`
}

View on GitHub (pinned to c0390bff16)

Solutions

1. Disconnect idle sessions to free slots (server.disconnect / release the session)
2. Increase maxAgentSessions configuration if the workload legitimately needs more
3. Check for session leaks: ensure every created session is released on client exit
4. Retry later with backoff — the limit may free up as sessions close

Example fix

// before
conn, err := r.connect(...) // err: "agent session limit reached: 64"
// after
if errors.Is(err, errAgentSessionLimit) {
    r.releaseStaleSessions()
    conn, err = r.connect(...) // retry
}

// check capacity before creating sessions
if r.sessionCount() >= maxAgentSessions {
    return fmt.Errorf("at capacity; release a session first")
}

sess, err := r.connect(cfg)
var capErr error
if errors.As(err, &capErr) && errors.Is(err, errAgentSessionLimit) {
    // wait/backoff then retry
    time.Sleep(backoff)
    sess, err = r.connect(cfg)
}

When it happens

Trigger: Calling session-creating RPCs (main.go:855 and main.go:921 paths) when len(r.sessions) >= maxAgentSessions; one at initial connect, another during control-session setup after which a stale server is disconnected and the limit is still hit.

Common situations: Long-lived agent sessions leaking (never disconnected), stress/load tests opening many sessions concurrently, or a low maxAgentSessions configuration in production.

Related errors

• %w: %d
• maximum Hive Agent sessions reached (%d)
• agent operation capacity is temporarily exhausted
• Cannot preserve lease: key changed concurrently; retry the s
• kingbase connection failed

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