{"record":{"id":"d4f0fb2863bf48ca","repo":"v2rayA/v2rayA","slug":"failed-to-set-pragma-s-w","errorCode":null,"errorMessage":"failed to set PRAGMA %s: %w","messagePattern":"failed to set PRAGMA (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"service/db/migrate.go","lineNumber":142,"sourceCode":"\t}\n\n\tdb, err := sql.Open(sqliteDriverName, dbPath)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to open SQLite database: %w\", err)\n\t}\n\n\t// Configure PRAGMAs for WAL mode and performance\n\tpragmas := []string{\n\t\t\"PRAGMA journal_mode=WAL\",\n\t\t\"PRAGMA synchronous=NORMAL\",\n\t\t\"PRAGMA busy_timeout=5000\",\n\t\t\"PRAGMA foreign_keys=ON\",\n\t\t\"PRAGMA cache_size=-8000\",\n\t}\n\tfor _, p := range pragmas {\n\t\tif _, err := db.Exec(p); err != nil {\n\t\t\tdb.Close()\n\t\t\treturn nil, fmt.Errorf(\"failed to set PRAGMA %s: %w\", p, err)\n\t\t}\n\t}\n\n\t// Initialize schema\n\tif err := InitSchema(db); err != nil {\n\t\tdb.Close()\n\t\treturn nil, fmt.Errorf(\"failed to initialize schema: %w\", err)\n\t}\n\n\treturn db, nil\n}\n\n// migrateSystemBucket migrates the system bucket to system_config table\nfunc migrateSystemBucket(boltDB *bbolt.DB, tx *sql.Tx) error {\n\treturn boltDB.View(func(btx *bbolt.Tx) error {\n\t\tbkt := btx.Bucket([]byte(\"system\"))\n\t\tif bkt == nil {\n\t\t\tlog.Info(\"No system bucket found, skipping\")","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/v2rayA/v2rayA/blob/71e5442fc548c05680ee55eae943e6c0afe9ac51/service/db/migrate.go#L124-L160","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Delete the leftover/invalid v2raya.db file (it is freshly created; removing it lets migration recreate it) and retry.","Check journal mode support: if the config dir is on NFS/SMB, move the config to a local filesystem.","Ensure no other process holds a lock on v2raya.db (second v2rayA instance, db browser).","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.","If WAL is unsupported, mount the volume locally or use a filesystem that supports shared memory mmap."],"exampleFix":"// before: v2raya.db corrupted from a prior failed run\nrm /etc/v2raya/v2raya.db\n// after: migration recreates a valid database\nsudo rm /etc/v2raya/v2raya.db && sudo systemctl restart v2raya","handlingStrategy":"validation","validationCode":"// check the target file is a valid SQLite db and the FS supports WAL before PRAGMAs\nfunc checkSQLiteFile(dbPath string) error {\n    if fi, err := os.Stat(dbPath); err == nil && fi.Size() > 0 {\n        f, err := os.Open(dbPath)\n        if err != nil {\n            return err\n        }\n        defer f.Close()\n        hdr := make([]byte, 16)\n        if _, err := f.Read(hdr); err != nil {\n            return err\n        }\n        if string(hdr[:15]) != \"SQLite format 3\\x00\" {\n            return fmt.Errorf(\"%s is not a valid SQLite database; remove it and retry\", dbPath)\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if _, err := db.Exec(\"PRAGMA journal_mode=WAL\"); err != nil {\n    db.Close()\n    if errors.Is(err, syscall.EIO) || strings.Contains(err.Error(), \"disk I/O error\") {\n        return fmt.Errorf(\"filesystem may not support WAL (NFS/SMB?); move config dir to a local FS: %w\", err)\n    }\n    return fmt.Errorf(\"failed to set PRAGMA: %w\", err)\n}","preventionTips":["Keep the database directory on a local filesystem, not NFS/SMB/CIFS.","Delete zero-byte or stale v2raya.db files left by failed runs before migrating.","Run only one v2rayA instance against the same config dir.","If WAL is unusable in your environment, document a journal_mode fallback (DELETE) for deployments.","Test PRAGMAs with the sqlite3 CLI when diagnosing."],"tags":["sqlite","pragma","wal","filesystem","migration"],"backgroundTag":"sqlite-wal-not-supported","analyzedSha":"71e5442fc548c05680ee55eae943e6c0afe9ac51","analyzedAt":"2026-09-05T20:04:37.459Z","contentChangedAt":"2026-09-05T20:04:37.459Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}