AdguardTeam/AdGuardHome · error

opening a transaction: %w

Error message

opening a transaction: %w

What it means

During stats.New, a write transaction could not be started on the bbolt database; the Begin(true) error is wrapped as 'opening a transaction'.

Source

Thrown at internal/stats/stats.go:197

	}

	if s.unitIDGen = newUnitID; conf.UnitID != nil {
		s.unitIDGen = conf.UnitID
	}

	// TODO(e.burkov):  Move the code below to the Start method.

	err = s.openDB()
	if err != nil {
		return nil, fmt.Errorf("opening database: %w", err)
	}

	var udb *unitDB
	id := s.unitIDGen()

	tx, err := s.db.Load().Begin(true)
	if err != nil {
		return nil, fmt.Errorf("opening a transaction: %w", err)
	}

	deleted := s.deleteOldUnits(tx, id-uint32(s.limit.Hours())-1)
	udb = s.loadUnitFromDB(tx, id)

	err = finishTxn(tx, deleted > 0)
	if err != nil {
		s.logger.Error("finishing transacation", slogutil.KeyError, err)
	}

	s.curr = newUnit(id)
	s.curr.deserialize(udb)

	s.logger.Debug("initialized")

	return s, nil
}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Ensure only one process opens the stats DB at a time
2. Check disk space and filesystem permissions
3. If it persists, delete the stats DB to reinitialize (losing history)

if _, err := os.Stat(dbPath); errors.Is(err, fs.ErrNotExist) { /* fresh start ok */ } else if err != nil { return err }

if _, err := stats.New(conf); err != nil { if strings.Contains(err.Error(), "transaction") { time.Sleep(time.Second); retry() } }

When it happens

Trigger: stats.New with a database that is locked, already in use by another process, closed, or on a full/read-only filesystem when Begin(true) is attempted.

Common situations: Concurrent processes opening the same bbolt file (bbolt takes an exclusive file lock), disk full, or the file being closed by another goroutine during initialization.

Related errors

• starting transaction: %w
• opening database: %w
• opening transaction: %w
• closing database: %w
• creating bucket: %w

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