{"record":{"id":"f33ad472e63241d4","repo":"t8y2/dbx","slug":"w-s","errorCode":null,"errorMessage":"%w: %s","messagePattern":"%w: %s","errorType":"exception","errorClass":"errAgentSessionNotFound","httpStatus":null,"severity":"error","filePath":"agents/drivers/xugu/main.go","lineNumber":955,"sourceCode":"\tr.connectMu.Unlock()\n\tif !controlAttached {\n\t\tr.releaseControl(session.controlKey)\n\t\tsession.controlKey = \"\"\n\t}\n\treturn err\n}\n\nfunc (r *runtimeServer) replaceSession(agentSessionID string, params connectParams) error {\n\t_ = r.closeSession(agentSessionID)\n\treturn r.openSession(agentSessionID, params)\n}\n\nfunc (r *runtimeServer) session(agentSessionID string) (*agentSession, error) {\n\tr.mu.RLock()\n\tsession := r.sessions[agentSessionID]\n\tr.mu.RUnlock()\n\tif session == nil {\n\t\treturn nil, fmt.Errorf(\"%w: %s\", errAgentSessionNotFound, agentSessionID)\n\t}\n\treturn session, nil\n}\n\nfunc (r *runtimeServer) closeSession(agentSessionID string) error {\n\tr.mu.Lock()\n\tsession := r.sessions[agentSessionID]\n\tdelete(r.sessions, agentSessionID)\n\tr.mu.Unlock()\n\tif session == nil {\n\t\treturn nil\n\t}\n\tsession.mu.Lock()\n\tdefer session.mu.Unlock()\n\terr := session.server.disconnect()\n\tr.releaseControl(session.controlKey)\n\treturn err\n}","sourceCodeStart":937,"sourceCodeEnd":973,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/xugu/main.go#L937-L973","documentation":"runtimeServer.session looks up an agent session by ID and wraps errAgentSessionNotFound ('agent session not found') with the requested ID when no entry exists. It is the lookup primitive used by nearly every RPC that takes an agentSessionId, so any unknown or expired ID surfaces as this error.","triggerScenarios":"Calling any RPC with an agentSessionId that was never opened, was already closed via close_session/disconnect, or vanished because the agent process restarted (sessions are in-memory).","commonSituations":"Client caches a session ID across an agent restart; double close_session; agent crash losing all sessions; typo or stale ID restored from a serialized state store.","solutions":["Re-open the session with open_session to obtain a new valid agentSessionId.","Check that the agent process has not restarted since the ID was issued.","Treat the error as terminal for that ID (sessionDisposition=quarantine in the RPC contract) and rebuild state rather than retrying with the same ID.","Verify the ID sent matches the one returned from open_session exactly."],"exampleFix":"// before\nrun(storedID, q) // agent restarted; ID is dead\n// after\nif _, err := rt.session(storedID); err != nil {\n  storedID = openSession(connStr)\n}\nrun(storedID, q)","handlingStrategy":"try-catch","validationCode":"// verify ID is non-empty and was issued by open_session\nif id == \"\" || !issuedIDs[id] {\n  return fmt.Errorf(\"refusing RPC with unknown session id %q\", id)\n}","typeGuard":"func isSessionNotFound(err error) bool {\n  return err != nil && strings.Contains(err.Error(), \"agent session not found\")\n}","tryCatchPattern":"if err := rpc(id); err != nil {\n  if isSessionNotFound(err) {\n    id = openSession(connStr) // rebuild state; do NOT retry same ID\n    rpc(id)\n  }\n}","preventionTips":["Reopen sessions after agent restarts; IDs are in-memory only.","Never persist agentSessionIds across process lifetimes.","Avoid double close_session; treat close as idempotent client-side.","Echo back the exact ID returned by open_session."],"tags":["session-not-found","stale-state","xugu"],"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-14T05:17:10.506Z"}