v2rayA/v2rayA · error

failed to open BoltDB: %w

Error message

failed to open BoltDB: %w

What it means

Raised in MigrateFromBoltDB when bbolt.Open in read-only mode fails on the detected BoltDB file: the file exists (stat succeeded) but cannot be opened — it may be locked by another process, not a valid BoltDB database, or unreadable. Migration from BoltDB to SQLite aborts.

Source

Thrown at service/db/migrate.go:42

	// Check if BoltDB file exists
	if _, err := os.Stat(boltPath); os.IsNotExist(err) {
		log.Info("No BoltDB file found at %s, skipping migration", boltPath)
		return nil
	}

	// Check if SQLite already exists (migration already done or fresh start)
	if _, err := os.Stat(sqlitePath); err == nil {
		log.Info("SQLite database already exists at %s, skipping migration", sqlitePath)
		return nil
	}

	log.Warn("Migrating from BoltDB to SQLite...")

	// Open BoltDB (read-only)
	boltDB, err := bbolt.Open(boltPath, 0600, &bbolt.Options{ReadOnly: true})
	if err != nil {
		return fmt.Errorf("failed to open BoltDB: %w", err)
	}
	defer boltDB.Close()

	// Create a fresh SQLite database independently (do NOT use GetDB)
	sqldb, err := createSQLiteDB(sqlitePath)
	if err != nil {
		return fmt.Errorf("failed to create SQLite database for migration: %w", err)
	}
	defer sqldb.Close()

	// Perform migration in a single transaction
	tx, err := sqldb.Begin()
	if err != nil {
		return fmt.Errorf("failed to begin SQLite transaction: %w", err)
	}
	defer func() {
		if p := recover(); p != nil {
			_ = tx.Rollback()

View on GitHub (pinned to 71e5442fc5)

Solutions

1. Stop other v2rayA instances holding the BoltDB lock
2. Check file permissions on the .db file
3. Remove the stale BoltDB file if migration is not needed

When it happens

Trigger: Thrown at service/db/migrate.go:42 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of v2rayA/v2rayA@71e5442fc5 (2026-09-05). Data as JSON: /api/errors/5567383abbe2db59. Report an issue: GitHub.