AdguardTeam/AdGuardHome · error

iterating over sessions: %w

Error message

iterating over sessions: %w

What it means

Iterating the sessions bucket with bbolt's ForEach aborted because the per-key handler returned an error. The wrapped error originates from bboltSessionHandler decoding each stored session (e.g., gob/JSON unmarshal failure on a session value).

Source

Thrown at internal/aghuser/sessionstorage.go:204

		"loading sessions from db",
		"stored", len(ds.sessions),
		"removed", removed,
	)

	return nil
}

// processSessions iterates over the sessions bucket and loads or removes
// sessions as needed.
func (ds *DefaultSessionStorage) processSessions(
	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

View on GitHub (pinned to b41aefbe51)

Solutions

1. Decode the wrapped error to find which entry failed; inspect bucket keys with a bbolt inspection tool
2. Reset the sessions store (users re-login) if entries are unsalvageable
3. Ship schema migrations or versioned decoders for session records

Example fix

# before
# old-format session entries fail decode
# after
bbolt buckets -path sessions.db -bucket sessions # inspect, then reset if needed

// pre-upgrade: decode all bucket values with the target session type; abort with a clear report on failure

if err := ds.processSessions(ctx, bkt); err != nil {
    if strings.Contains(err.Error(), "iterating over sessions") { reset sessions store as a fallback (users re-login) }
}

When it happens

Trigger: A stored session key/value pair in the bucket cannot be decoded by the current session handler: schema drift after upgrade, corrupted entry, or a value written by a different storage version.

Common situations: Upgrading the app across a session-structure change without clearing sessions.db; crash-corrupted bbolt entries; mixed-version replicas sharing a data directory.

Related errors

• processing sessions: %w
• loading sessions: %w
• deleting sessions: %w
• length of the data is less than expected: got %d
• login: expected length %d, got %d

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