AdguardTeam/AdGuardHome · error

processing sessions: %w

Error message

processing sessions: %w

What it means

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.

Source

Thrown at internal/aghuser/sessionstorage.go:169

	if err != nil {
		return fmt.Errorf("starting transaction: %w", err)
	}

	needRollback := true
	defer func() {
		if needRollback {
			err = errors.WithDeferred(err, tx.Rollback())
		}
	}()

	bkt := tx.Bucket([]byte(bboltBucketSessions))
	if bkt == nil {
		return nil
	}

	removed, err := ds.processSessions(ctx, bkt)
	if err != nil {
		return fmt.Errorf("processing sessions: %w", err)
	}

	if removed == 0 {
		ds.logger.DebugContext(ctx, "loading sessions from db", "stored", len(ds.sessions))

		return nil
	}

	needRollback = false
	err = tx.Commit()
	if err != nil {
		return fmt.Errorf("committing transaction: %w", err)
	}

	ds.logger.DebugContext(
		ctx,
		"loading sessions from db",
		"stored", len(ds.sessions),

View on GitHub (pinned to b41aefbe51)

Solutions

1. Identify the offending entries by decoding the wrapped error / inspecting the bucket with bbolt CLI tools
2. Delete the sessions database (forces re-login) if individual entries cannot be salvaged
3. Add forward-compatible migrations for session schema changes before deploying

Example fix

# before
# app upgraded, old session encoding now invalid
# after
rm /var/lib/app/sessions.db && systemctl restart app

// before upgrade: snapshot and validate decodability of the bucket
// decode every value with the new schema; quarantine failures

if err := ds.loadSessions(ctx); err != nil {
    if strings.Contains(err.Error(), "processing sessions") { move sessions.db aside and restart (forced re-login) }
}

When it happens

Trigger: 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.

Common situations: Upgrade changes the serialized session format without a migration; manual edits to the bbolt file; partial writes from a crash mid-commit.

Related errors

• loading sessions: %w
• iterating over sessions: %w
• deleting sessions: %w
• starting transaction: %w
• length of the data is less than expected: got %d

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