AdguardTeam/AdGuardHome · error

creating bucket: %w

Error message

creating bucket: %w

What it means

While flushing an aggregated stats unit to bbolt, CreateBucketIfNotExists failed; the error is wrapped as 'creating bucket'.

Source

Thrown at internal/stats/unit.go:348

	for _, s := range e.UpstreamStats {
		if s.IsCached || s.Error != nil {
			continue
		}

		addr := s.Address
		u.upstreamsResponses[addr]++
		u.upstreamsTimeSum[addr] += uint64(s.QueryDuration.Microseconds())
	}
}

// flushUnitToDB puts udb to the database at id.
func (s *StatsCtx) flushUnitToDB(udb *unitDB, tx *bbolt.Tx, id uint32) (err error) {
	s.logger.Debug("flushing unit", "id", id, "req_num", udb.NTotal)

	bkt, err := tx.CreateBucketIfNotExists(idToUnitName(id))
	if err != nil {
		return fmt.Errorf("creating bucket: %w", err)
	}

	buf := &bytes.Buffer{}
	err = gob.NewEncoder(buf).Encode(udb)
	if err != nil {
		return fmt.Errorf("encoding unit: %w", err)
	}

	err = bkt.Put([]byte{0}, buf.Bytes())
	if err != nil {
		return fmt.Errorf("putting unit to database: %w", err)
	}

	return nil
}

func convertTopSlice(a []countPair) (m []map[string]uint64) {
	m = make([]map[string]uint64, 0, len(a))

View on GitHub (pinned to b41aefbe51)

Solutions

1. Check disk space and DB file permissions
2. Ensure Close/flush is not racing with DB close or reset
3. Restart with a fresh stats DB if corruption is suspected

if err := db.View(func(tx *bbolt.Tx) error { _, err := tx.CreateBucketIfNotExistsIfWritable(); return err }); err != nil { /* abort flush */ }

if err := s.Close(); err != nil { log.Printf("flush failed: %v", err) }

When it happens

Trigger: flushUnitToDB (via Close, periodic flush, or populateTestData) hitting a read-only/closed transaction, disk full, or bbolt-internal errors creating the per-unit bucket.

Common situations: Disk exhaustion, transaction invalidated by a prior error, DB closed concurrently with a flush.

Related errors

• opening database: %w
• opening a transaction: %w
• opening transaction: %w
• closing database: %w
• putting unit to database: %w

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