v2rayA/v2rayA · error

failed to set PRAGMA %s: %w

Error message

failed to set PRAGMA %s: %w

What it means

createSQLiteDB issues a set of PRAGMA statements (WAL journal mode, synchronous=NORMAL, busy_timeout, foreign_keys, cache_size) on the freshly opened connection. A PRAGMA failure means the SQLite engine rejected or could not execute one of these settings — typically WAL mode unavailable on the filesystem, a corrupt/unreadable database file, or a locked/busy database.

Source

Thrown at service/db/migrate.go:142

	}

	db, err := sql.Open(sqliteDriverName, dbPath)
	if err != nil {
		return nil, fmt.Errorf("failed to open SQLite database: %w", err)
	}

	// Configure PRAGMAs for WAL mode and performance
	pragmas := []string{
		"PRAGMA journal_mode=WAL",
		"PRAGMA synchronous=NORMAL",
		"PRAGMA busy_timeout=5000",
		"PRAGMA foreign_keys=ON",
		"PRAGMA cache_size=-8000",
	}
	for _, p := range pragmas {
		if _, err := db.Exec(p); err != nil {
			db.Close()
			return nil, fmt.Errorf("failed to set PRAGMA %s: %w", p, err)
		}
	}

	// Initialize schema
	if err := InitSchema(db); err != nil {
		db.Close()
		return nil, fmt.Errorf("failed to initialize schema: %w", err)
	}

	return db, nil
}

// migrateSystemBucket migrates the system bucket to system_config table
func migrateSystemBucket(boltDB *bbolt.DB, tx *sql.Tx) error {
	return boltDB.View(func(btx *bbolt.Tx) error {
		bkt := btx.Bucket([]byte("system"))
		if bkt == nil {
			log.Info("No system bucket found, skipping")

View on GitHub (pinned to 71e5442fc5)

Solutions

1. Delete the leftover/invalid v2raya.db file (it is freshly created; removing it lets migration recreate it) and retry.
2. Check journal mode support: if the config dir is on NFS/SMB, move the config to a local filesystem.
3. Ensure no other process holds a lock on v2raya.db (second v2rayA instance, db browser).
4. Identify which PRAGMA failed from the wrapped message and run it manually with the sqlite3 CLI against the file to see the underlying SQLite error.
5. If WAL is unsupported, mount the volume locally or use a filesystem that supports shared memory mmap.

Example fix

// before: v2raya.db corrupted from a prior failed run
rm /etc/v2raya/v2raya.db
// after: migration recreates a valid database
sudo rm /etc/v2raya/v2raya.db && sudo systemctl restart v2raya

// check the target file is a valid SQLite db and the FS supports WAL before PRAGMAs
func checkSQLiteFile(dbPath string) error {
    if fi, err := os.Stat(dbPath); err == nil && fi.Size() > 0 {
        f, err := os.Open(dbPath)
        if err != nil {
            return err
        }
        defer f.Close()
        hdr := make([]byte, 16)
        if _, err := f.Read(hdr); err != nil {
            return err
        }
        if string(hdr[:15]) != "SQLite format 3\x00" {
            return fmt.Errorf("%s is not a valid SQLite database; remove it and retry", dbPath)
        }
    }
    return nil
}

if _, err := db.Exec("PRAGMA journal_mode=WAL"); err != nil {
    db.Close()
    if errors.Is(err, syscall.EIO) || strings.Contains(err.Error(), "disk I/O error") {
        return fmt.Errorf("filesystem may not support WAL (NFS/SMB?); move config dir to a local FS: %w", err)
    }
    return fmt.Errorf("failed to set PRAGMA: %w", err)
}

When it happens

Trigger: db.Exec(p) fails for one of PRAGMA journal_mode=WAL / synchronous=NORMAL / busy_timeout=5000 / foreign_keys=ON / cache_size=-8000: the file created by os.Create is not a valid SQLite database (e.g. it was pre-created by another tool with different content), the filesystem does not support WAL's shared-memory files (some network mounts), or the database is locked by another connection.

Common situations: Config directory on NFS/SMB/CIFS where WAL mode fails; leftover zero-byte or corrupt v2raya.db from a failed previous run; another v2rayA instance holding a lock on the new database.

Related errors

• failed to rename bolt.db to bolt.db.bak: %w
• failed to create SQLite database file: %w
• bolt.db exists, migration required
• failed to migrate system bucket: %w
• failed to migrate touch bucket: %w

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