{"record":{"id":"018dfa0d71782d5c","repo":"t8y2/dbx","slug":"agent-session-not-found","errorCode":null,"errorMessage":"agent session not found","messagePattern":"agent session not found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/drivers/xugu/protocol_error.go","lineNumber":18,"sourceCode":"package main\n\nimport (\n\t\"context\"\n\t\"database/sql\"\n\t\"database/sql/driver\"\n\t\"errors\"\n\t\"fmt\"\n\t\"io\"\n\t\"net\"\n\t\"regexp\"\n\t\"strconv\"\n\t\"strings\"\n)\n\nvar (\n\terrAgentSessionLimit     = errors.New(\"agent session limit reached\")\n\terrAgentSessionNotFound  = errors.New(\"agent session not found\")\n\terrXuguOperationTimeout  = errors.New(\"xugu operation timed out\")\n\terrXuguOperationCanceled = errors.New(\"xugu operation canceled\")\n\n\t// go-xugu-driver exposes server errors as plain strings rather than a typed\n\t// error. Match only the stable server error header and keep the complete\n\t// original message for diagnostics. A response can contain more than one\n\t// Xugu error; vendorCode intentionally records the first/top-level code.\n\txuguServerErrorHeader = regexp.MustCompile(`(?im)^[\\t ]*(?:error:[\\t ]*)?\\[[\\t ]*E([0-9]{1,9})(?:[\\t ]+L([0-9]+))?(?:[\\t ]+C([0-9]+))?[\\t ]*\\]`)\n\txuguQueryTimeout      = regexp.MustCompile(`(?i)^query timed out after [1-9][0-9]*s$`)\n)\n\ntype rpcError struct {\n\tCode    int           `json:\"code\"`\n\tMessage string        `json:\"message\"`\n\tData    *rpcErrorData `json:\"data,omitempty\"`\n}\n\ntype rpcErrorData struct {","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/xugu/protocol_error.go#L1-L36","documentation":"errAgentSessionNotFound is a sentinel error thrown when a session lookup by agentSessionID fails (session == nil). Callers wrap it with the session ID via %w so errors.Is can detect it; classifyRPCError categorizes it as a protocol error with SessionDisposition \"quarantine\".","triggerScenarios":"Calling an RPC that resolves a session by ID (main.go:955 path) with an ID that was never registered, or that was already released/removed after disconnect.","commonSituations":"Client retrying with a stale session ID after server restart, double-disconnect invalidating the session, or the server quarantining a failed session while the client still references it.","solutions":["Reconnect and obtain a fresh agent session ID before retrying","Verify the session ID matches one returned by the original connect call","Handle disconnect semantics: once released, the ID is permanently invalid","Inspect the structured error's SessionDisposition field to confirm quarantine"],"exampleFix":"// before\nresp, err := rpc.Call(sessionID) // err: \"agent session not found: abc\"\nretry(sessionID)\n// after\nif errors.Is(err, errAgentSessionNotFound) {\n    sessionID = r.connect(...) // new session\n    resp, err = rpc.Call(sessionID)\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"resp, err := callRPC(sessionID, req)\nif err != nil && errors.Is(err, errAgentSessionNotFound) {\n    sessionID = reconnect() // obtain a fresh session\n    resp, err = callRPC(sessionID, req)\n}","preventionTips":["Treat session IDs as ephemeral: re-create after any disconnect or server restart","Never reuse a session ID after calling disconnect","Inspect SessionDisposition in structured errors to detect quarantined sessions early"],"tags":["xugu","session","stale-state","protocol"],"backgroundTag":"session-not-found","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"}