{"record":{"id":"b3e1c9fb0a791347","repo":"t8y2/dbx","slug":"w-d","errorCode":null,"errorMessage":"%w: %d","messagePattern":"%w: %d","errorType":"exception","errorClass":"errAgentSessionLimit","httpStatus":null,"severity":"error","filePath":"agents/drivers/xugu/main.go","lineNumber":855,"sourceCode":"\tsession, err := r.session(agentSessionID)\n\tif err != nil {\n\t\treturn nil, false, err\n\t}\n\t// Database, schema, transaction, and cursor state are connection-scoped.\n\tsession.mu.Lock()\n\tdefer session.mu.Unlock()\n\treturn session.server.dispatch(method, params)\n}\n\nfunc (r *runtimeServer) openSession(agentSessionID string, params connectParams) error {\n\tr.mu.Lock()\n\tif _, exists := r.sessions[agentSessionID]; exists {\n\t\tr.mu.Unlock()\n\t\treturn fmt.Errorf(\"agent session already exists: %s\", agentSessionID)\n\t}\n\tif len(r.sessions) >= maxAgentSessions {\n\t\tr.mu.Unlock()\n\t\treturn fmt.Errorf(\"%w: %d\", errAgentSessionLimit, maxAgentSessions)\n\t}\n\tr.mu.Unlock()\n\n\tserver := newServer()\n\t// APP_NAME is useful for identifying a business session from SYS_SESSIONS,\n\t// but some Xugu server/driver combinations close the socket when an ordinary\n\t// user sends this optional login attribute. Keep the original parameters for\n\t// the permission-degraded path and add APP_NAME only when SYSTEM control is\n\t// actually available.\n\tbusinessParams := params\n\tif !xuguControlSessionEligible(params) {\n\t\tr.connectMu.Lock()\n\t\t_, err := server.connectWithControl(businessParams, nil, false)\n\t\tr.connectMu.Unlock()\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\treturn r.registerSession(agentSessionID, server, \"\")","sourceCodeStart":837,"sourceCodeEnd":873,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/xugu/main.go#L837-L873","documentation":"The Xugu agent driver caps concurrent agent sessions at maxAgentSessions (256). openSession checks the session map before dialing the database and returns a wrapped errAgentSessionLimit ('agent session limit reached') with the current count when capacity is exhausted. The sentinel is classified as a retryable resource error because the check happens before any DB work starts.","triggerScenarios":"Calling open_session (or any flow through runtimeServer.openSession) when len(r.sessions) already equals maxAgentSessions=256, e.g. 256 prior sessions were opened and never closed.","commonSituations":"Client leaks sessions by opening repeatedly without close_session; a hung agent process accumulates sessions; load tests open more than 256 parallel connections; reconnect storms after network blips leave stale sessions registered.","solutions":["Close idle sessions with close_session/disconnect so len(r.sessions) drops below 256, then retry.","Restart the agent process to clear all in-memory sessions if ownership of leaked sessions is unclear.","Retry the open later — the error is classified Retryable=true, category=resource, because no DB operation had started.","Audit the client for unbalanced open/close calls; fix the leak rather than raising the limit."],"exampleFix":"// before (leaking sessions)\nfor _, q := range queries {\n  id := openSession(connStr) // never closed -> hits 256 cap\n  run(id, q)\n}\n// after\ndefer closeSession(id)\nrun(id, q)","handlingStrategy":"retry","validationCode":"// client-side bookkeeping before calling open_session\nif activeSessions >= 256 {\n  return fmt.Errorf(\"local guard: %d sessions open, close some first\", activeSessions)\n}","typeGuard":null,"tryCatchPattern":"if err := openSession(); err != nil {\n  if strings.Contains(err.Error(), \"agent session limit reached\") {\n    time.Sleep(backoff)\n    retry() // classified retryable/resource\n  }\n}","preventionTips":["Always pair open_session with close_session via defer/finally.","Track locally opened session count and stay below 256.","Clean up leaked sessions after client crashes (restart or close them).","Alert when session count approaches the cap."],"tags":["session-limit","capacity","xugu","retryable"],"backgroundTag":"agent-session-limit-reached","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}