AdguardTeam/AdGuardHome · error

storing session: %w

Error message

storing session: %w

What it means

Returned by DefaultSessionStorage.New (called from addSession) when persisting a newly created session via store() fails. The wrapped error is usually one of the transaction errors (begin/create-bucket/put/commit) from bbolt.

Source

Thrown at internal/aghuser/sessionstorage.go:335

	return data
}

// type check
var _ SessionStorage = (*DefaultSessionStorage)(nil)

// New implements the [SessionStorage] interface for *DefaultSessionStorage.
func (ds *DefaultSessionStorage) New(ctx context.Context, u *User) (s *Session, err error) {
	s = &Session{
		Token:     NewSessionToken(),
		UserID:    u.ID,
		UserLogin: u.Login,
		Expire:    ds.clock.Now().Add(ds.sessionTTL),
	}

	err = ds.store(s)
	if err != nil {
		return nil, fmt.Errorf("storing session: %w", err)
	}

	ds.mu.Lock()
	defer ds.mu.Unlock()

	ds.sessions[s.Token] = s

	return s, nil
}

// store saves a web user session in the bbolt database.
func (ds *DefaultSessionStorage) store(s *Session) (err error) {
	tx, err := ds.db.Begin(true)
	if err != nil {
		return fmt.Errorf("starting transaction: %w", err)
	}

	needRollback := true

View on GitHub (pinned to b41aefbe51)

Solutions

1. Free disk space and ensure the data directory is writable by the process user
2. Ensure only one instance uses the work directory
3. Inspect the wrapped error for the exact bbolt stage (begin/put/commit) and address that
4. Restart the service if the file lock is stale

// ensure the data dir is writable before login flows
if err := checkWritable(filepath.Join(workDir, "sessions.db")); err != nil { return err }

// surface to the login handler as a 500; login cannot proceed without persistence
if err := storage.New(ctx, u); err != nil { http.Error(w, "session storage unavailable", http.StatusInternalServerError) }

When it happens

Trigger: User logs in and the code path addSession -> New -> store fails: db file unwritable, disk full, db locked by another process, or bucket creation rejected.

Common situations: Disk full; read-only volume; running two instances on the same work dir; permissions changed after moving the data dir (Docker volume issues).

Related errors

• loading sessions: %w
• deleting sessions: %w
• processing sessions: %w
• iterating over sessions: %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/66f4c931c717c3cf. Report an issue: GitHub.