{"record":{"id":"46e8596ae98ef8f5","repo":"AdguardTeam/AdGuardHome","slug":"loading-sessions-w","errorCode":null,"errorMessage":"loading sessions: %w","messagePattern":"loading sessions: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/aghuser/sessionstorage.go","lineNumber":128,"sourceCode":"\tdbFilename := conf.DBPath\n\tds.db, err = bbolt.Open(dbFilename, aghos.DefaultPermFile, &bbolt.Options{\n\t\tTimeout: dbOpenTimeout,\n\t\tLogger:  newBBoltLogger(ctx, ds.logger),\n\t})\n\tif err != nil {\n\t\tds.logger.ErrorContext(ctx, \"opening db\", \"filename\", dbFilename, slogutil.KeyError, err)\n\t\tif errors.Is(err, berrors.ErrInvalid) {\n\t\t\tconst s = \"AdGuard Home cannot be initialized due to an incompatible file system.\\n\" +\n\t\t\t\t\"Please read the explanation here: https://adguard-dns.io/kb/adguard-home/getting-started/#limitations\"\n\t\t\tslogutil.PrintLines(ctx, ds.logger, slog.LevelError, \"\", s)\n\t\t}\n\n\t\treturn nil, err\n\t}\n\n\terr = ds.loadSessions(ctx)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"loading sessions: %w\", err)\n\t}\n\n\treturn ds, nil\n}\n\n// newBBoltLogger returns a new [*bbolt.DefaultLogger] that logs messages using\n// the given [slog.Logger].  l must not be nil.\nfunc newBBoltLogger(ctx context.Context, l *slog.Logger) (bl *bbolt.DefaultLogger) {\n\tbl = &bbolt.DefaultLogger{\n\t\tLogger: slog.NewLogLogger(l.Handler(), slog.LevelDebug),\n\t}\n\n\tif l.Enabled(ctx, slog.LevelDebug) {\n\t\tbl.EnableDebug()\n\t}\n\n\treturn bl\n}","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/AdguardTeam/AdGuardHome/blob/b41aefbe51c8dde65e2c50f093996afa0502edf9/internal/aghuser/sessionstorage.go#L110-L146","documentation":"The default session storage constructor failed while loading persisted web-user sessions from the bbolt database file. This wraps the concrete failure from loadSessions (transaction start, iteration, or commit).","triggerScenarios":"Calling NewDefaultSessionStorage on a bbolt file that cannot be read or processed: corrupted database, a database created by an incompatible schema/version, or a file the process cannot lock.","commonSituations":"Upgrading the application across a session-store schema change without migration; a bbolt file truncated by an unclean shutdown; another process holding a flock on the same sessions.db.","solutions":["Inspect the wrapped error to identify the failing phase (transaction/iterate/commit)","If the file is corrupt, stop the service, back up and delete/recreate sessions.db (users must re-login)","Ensure only one instance of the service accesses the sessions database file","Check file permissions on the sessions db path for the service user"],"exampleFix":"# before\n# corrupted sessions.db blocks startup\n# after\nmv /var/lib/app/sessions.db /var/lib/app/sessions.db.bak\n# restart; users re-authenticate","handlingStrategy":"try-catch","validationCode":"f, err := os.OpenFile(sessionsPath, os.O_RDWR, 0o600)\nif err != nil { return fmt.Errorf(\"sessions db unusable: %w\", err) }\nf.Close()","typeGuard":null,"tryCatchPattern":"ds, err := aghuser.NewDefaultSessionStorage(ctx, logger, path)\nif err != nil {\n    if strings.Contains(err.Error(), \"loading sessions\") { back up & reset the sessions file }\n}","preventionTips":["Run one service instance per sessions.db","Back up sessions.db before upgrades","Ensure service-user write access to the data directory"],"tags":["sessions","bbolt","storage","startup","database"],"backgroundTag":"database-open-failed","analyzedSha":"b41aefbe51c8dde65e2c50f093996afa0502edf9","analyzedAt":"2026-08-27T04:57:55.097Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}