{"record":{"id":"87999ec866df8709","repo":"AdguardTeam/AdGuardHome","slug":"processing-sessions-w","errorCode":null,"errorMessage":"processing sessions: %w","messagePattern":"processing sessions: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/aghuser/sessionstorage.go","lineNumber":169,"sourceCode":"\tif err != nil {\n\t\treturn fmt.Errorf(\"starting transaction: %w\", err)\n\t}\n\n\tneedRollback := true\n\tdefer func() {\n\t\tif needRollback {\n\t\t\terr = errors.WithDeferred(err, tx.Rollback())\n\t\t}\n\t}()\n\n\tbkt := tx.Bucket([]byte(bboltBucketSessions))\n\tif bkt == nil {\n\t\treturn nil\n\t}\n\n\tremoved, err := ds.processSessions(ctx, bkt)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"processing sessions: %w\", err)\n\t}\n\n\tif removed == 0 {\n\t\tds.logger.DebugContext(ctx, \"loading sessions from db\", \"stored\", len(ds.sessions))\n\n\t\treturn nil\n\t}\n\n\tneedRollback = false\n\terr = tx.Commit()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"committing transaction: %w\", err)\n\t}\n\n\tds.logger.DebugContext(\n\t\tctx,\n\t\t\"loading sessions from db\",\n\t\t\"stored\", len(ds.sessions),","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/AdguardTeam/AdGuardHome/blob/b41aefbe51c8dde65e2c50f093996afa0502edf9/internal/aghuser/sessionstorage.go#L151-L187","documentation":"While scanning the sessions bucket during startup load, per-key session processing failed. This wraps the error returned by the session handler over bbolt's ForEach — typically an unmarshal failure of a stored session value.","triggerScenarios":"processSessions iterates stored session entries; a value that cannot be decoded into the current session struct (schema change, different UserID/SessionID format, binary garbage from corruption) makes the handler return an error that aborts iteration.","commonSituations":"Upgrade changes the serialized session format without a migration; manual edits to the bbolt file; partial writes from a crash mid-commit.","solutions":["Identify the offending entries by decoding the wrapped error / inspecting the bucket with bbolt CLI tools","Delete the sessions database (forces re-login) if individual entries cannot be salvaged","Add forward-compatible migrations for session schema changes before deploying"],"exampleFix":"# before\n# app upgraded, old session encoding now invalid\n# after\nrm /var/lib/app/sessions.db && systemctl restart app","handlingStrategy":"fallback","validationCode":"// before upgrade: snapshot and validate decodability of the bucket\n// decode every value with the new schema; quarantine failures","typeGuard":null,"tryCatchPattern":"if err := ds.loadSessions(ctx); err != nil {\n    if strings.Contains(err.Error(), \"processing sessions\") { move sessions.db aside and restart (forced re-login) }\n}","preventionTips":["Version session records and add migration code on schema changes","Clear/rotate session stores across breaking upgrades"],"tags":["sessions","bbolt","deserialization","schema","startup"],"backgroundTag":"schema-deserialization-failed","analyzedSha":"b41aefbe51c8dde65e2c50f093996afa0502edf9","analyzedAt":"2026-08-27T04:57:55.097Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}