AdguardTeam/AdGuardHome · error

creating bucket: %w

Error message

creating bucket: %w

What it means

store() could not create the 'sessions' bucket inside the writable transaction (tx.CreateBucketIfNotExists). bbolt fails here if the bucket name is invalid, the db is in a read-only transaction, or free-page allocation fails on a corrupted/full database.

Source

Thrown at internal/aghuser/sessionstorage.go:362

}

// 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
	defer func() {
		if needRollback {
			err = errors.WithDeferred(err, tx.Rollback())
		}
	}()

	bkt, err := tx.CreateBucketIfNotExists([]byte(bboltBucketSessions))
	if err != nil {
		return fmt.Errorf("creating bucket: %w", err)
	}

	err = bkt.Put(s.Token[:], bboltEncode(s))
	if err != nil {
		return fmt.Errorf("putting data: %w", err)
	}

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

	return nil
}

// FindByToken implements the [SessionStorage] interface for *DefaultSessionStorage.
func (ds *DefaultSessionStorage) FindByToken(ctx context.Context, t SessionToken) (s *Session, err error) {

View on GitHub (pinned to b41aefbe51)

Solutions

1. Free disk space / verify filesystem health
2. Validate the db with bbolt check; delete the sessions db if corrupt (it is rebuildable)
3. Recreate the work directory if the whole db is damaged

// log and degrade: keep the in-memory session map even if persistence fails

When it happens

Trigger: First session write on a fresh or damaged db where bucket creation fails; database file corrupted so page allocation errors.

Common situations: Corrupted db after unclean shutdown; insufficient disk space for page allocation; incompatible bbolt version reading the file.

Related errors

• starting transaction: %w
• loading sessions: %w
• processing sessions: %w
• committing transaction: %w
• iterating over sessions: %w

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