AdguardTeam/AdGuardHome · error

deleting sessions: %w

Error message

deleting sessions: %w

What it means

Thrown when DefaultSessionStorage fails to delete one or more expired/invalid sessions from the underlying bbolt bucket during processSessions (invoked from loadSessions). Individual bkt.Delete errors are joined with errors.Join and wrapped as 'deleting sessions'. It indicates the bbolt database rejected a Delete inside the read/write transaction used at startup to purge stale sessions.

Source

Thrown at internal/aghuser/sessionstorage.go:215

	ctx context.Context,
	bkt *bbolt.Bucket,
) (removed int, err error) {
	invalidSessions := [][]byte{}

	err = bkt.ForEach(ds.bboltSessionHandler(ctx, &invalidSessions))
	if err != nil {
		return 0, fmt.Errorf("iterating over sessions: %w", err)
	}

	var errs []error
	for _, s := range invalidSessions {
		if err = bkt.Delete(s); err != nil {
			errs = append(errs, err)
		}
	}

	if err = errors.Join(errs...); err != nil {
		return 0, fmt.Errorf("deleting sessions: %w", err)
	}

	return len(invalidSessions), nil
}

// bboltSessionHandler returns a function for [bbolt.Bucket.ForEach] that
// iterates over stored sessions, deserializes them, and logs any errors
// encountered.  The returned error is always nil, as these errors are
// considered non-critical to stop the iteration process.
func (ds *DefaultSessionStorage) bboltSessionHandler(
	ctx context.Context,
	invalidSessions *[][]byte,
) (fn func(k, v []byte) (err error)) {
	now := ds.clock.Now()

	return func(k, v []byte) (err error) {
		s, err := bboltDecode(v)
		if err != nil {

View on GitHub (pinned to b41aefbe51)

Solutions

1. Stop other AdGuard Home instances using the same data directory and retry
2. Check file permissions / read-only mounts on the sessions db file
3. Run bbolt consistency checks (e.g. bbolt check) on the database file
4. If corruption is confirmed, delete the sessions db file — sessions are ephemeral and will be recreated

Example fix

// before: sharing one work dir between two instances
// after: give each instance its own -w work directory
./AdGuardHome -w /var/lib/adguardhome1
./AdGuardHome -w /var/lib/adguardhome2

// ignore deletion failures during load; sessions are ephemeral and purged next cycle
_, err := storage.LoadSessions(ctx)
if err != nil && !strings.Contains(err.Error(), "deleting sessions") { return err }

When it happens

Trigger: Calling NewSessionStorage / loadSessions on a database where deleting a key fails: bucket was deleted concurrently, transaction was closed, database file is corrupted, or the bucket is read-only / file permissions changed.

Common situations: Corrupted session.db bbolt file after a crash; two AdGuard Home instances sharing the same data/work folder; read-only filesystem or permission loss on the data directory; upgrading between versions with an incompatible bbolt schema.

Related errors

• loading sessions: %w
• processing sessions: %w
• storing session: %w
• starting transaction: %w
• iterating over sessions: %w

AI-assisted analysis of AdguardTeam/AdGuardHome@b41aefbe51 (2026-08-27). Data as JSON: /api/errors/c443700dd742bffd. Report an issue: GitHub.