util: detect and warn when using exFAT on macOS

willcl-ark · willcl-ark · commit eb68bb48ab2b · 2025-08-04T10:37:10.000+01:00
exFAT is known to cause corruption on macOS. See #28552. Therefore we should warn when using this fs format for either the blocks or data directories on macOS.
diff --git a/doc/files.md b/doc/files.md
@@ -16,6 +16,8 @@
 
   - [Berkeley DB database based wallets](#berkeley-db-database-based-wallets)
 
+- [Filesystem recommendations](#filesystem-recommendations)
+
 - [Notes](#notes)
 
 ## Data directory location
@@ -123,6 +125,12 @@ Subdirectory | File(s)           | Description
 `./`         | `wallet.dat`      | Personal wallet (a BDB database) with keys and transactions
 `./`         | `.walletlock`     | BDB wallet lock file
 
+## Filesystem recommendations
+
+When choosing a filesystem for the data directory (`datadir`) or blocks directory (`blocksdir`), some filesystems should be avoided:
+
+- **macOS**: The exFAT filesystem should not be used. There have been multiple reports of database and other corruption when using exFAT on macOS for Bitcoin Core. This appears to be due to filesystem-level issues with exFAT on the macOS operating system. See [Issue #31454](https://github.com/bitcoin/bitcoin/issues/31454) for more details.
+
 ## Notes
 
 <a name="note1">1</a>. The `/` (slash, U+002F) is used as the platform-independent path component separator in this document.
diff --git a/src/init.cpp b/src/init.cpp
@@ -1841,6 +1841,35 @@ bool AppInitMain(NodeContext& node, interfaces::BlockAndHeaderTipInfo* tip_info)
         }
     }
 
+#ifdef __APPLE__
+    // Warn about exFAT filesystem usage on macOS
+    std::vector<std::string> exfat_paths;
+    std::vector<std::string> error_paths;
+
+    auto check_fs = [&](const fs::path& path, std::string_view desc) {
+        FSType fs_type = GetFilesystemType(path);
+        std::string path_desc = strprintf("%s (\"%s\")", desc, fs::PathToString(path));
+        if (fs_type == FSType::EXFAT) {
+            exfat_paths.push_back(path_desc);
+        } else if (fs_type == FSType::ERROR) {
+            error_paths.push_back(path_desc);
+        }
+    };
+
+    check_fs(args.GetDataDirNet(), "data directory");
+    check_fs(args.GetBlocksDirPath(), "blocks directory");
+
+    if (!exfat_paths.empty()) {
+        InitWarning(strprintf(_("The following paths are on exFAT which is known to have intermittent corruption problems on macOS: %s. "
+            "Move these directories to a non-exFAT formatted drive to avoid corruption."),
+            util::Join(exfat_paths, ", ")));
+    }
+
+    if (!error_paths.empty()) {
+        LogInfo("Failed to detect filesystem type for: %s\n", util::Join(error_paths, ", "));
+    }
+#endif
+
 #if HAVE_SYSTEM
     const std::string block_notify = args.GetArg("-blocknotify", "");
     if (!block_notify.empty()) {
diff --git a/src/util/fs_helpers.cpp b/src/util/fs_helpers.cpp
@@ -30,6 +30,11 @@
 #include <shlobj.h>
 #endif // WIN32
 
+#ifdef __APPLE__
+#include <sys/mount.h>
+#include <sys/param.h>
+#endif
+
 /** Mutex to protect dir_locks. */
 static GlobalMutex cs_dir_locks;
 /** A map that contains all the currently held directory locks. After
@@ -298,3 +303,17 @@ std::optional<fs::perms> InterpretPermString(const std::string& s)
         return std::nullopt;
     }
 }
+
+#ifdef __APPLE__
+FSType GetFilesystemType(const fs::path& path) {
+    struct statfs fs_info;
+    if (statfs(path.c_str(), &fs_info) != 0) {
+        return FSType::ERROR;
+    }
+
+    if (strcmp(fs_info.f_fstypename, "exfat") == 0) {
+        return FSType::EXFAT;
+    }
+    return FSType::OTHER;
+}
+#endif
diff --git a/src/util/fs_helpers.h b/src/util/fs_helpers.h
@@ -14,6 +14,23 @@
 #include <limits>
 #include <optional>
 
+#ifdef __APPLE__
+enum class FSType {
+    EXFAT,
+    OTHER,
+    ERROR
+};
+
+/**
+ * Detect filesystem type for a given path.
+ * Currently identifies exFAT filesystems which cause issues on MacOS.
+ *
+ * @param[in] path The directory path to check
+ * @return FSType enum indicating the filesystem type
+ */
+FSType GetFilesystemType(const fs::path& path);
+#endif
+
 /**
  * Ensure file contents are fully committed to disk, using a platform-specific
  * feature analogous to fsync().
