Block copying or moving files too large for the destination filesystem (FAT32's 4 GB cap)

A FAT32 USB stick silently failed a 5 GB copy partway through (~4 GB in) because nothing checked the destination's per-file limit. Now copy and cross-filesystem move pre-flight that limit during the scan and show a clear, all-or-nothing dialog before writing a byte — even when the offending file is buried deep under one of several selected folders.

- New `file_system::filesystem_kind` module: classifies the destination (`FilesystemKind`) and derives its per-file cap (`MaxFileSize`). Only FAT32 (`msdos`/`vfat`) is `Limited` (4 GiB − 1); exFAT, NTFS, APFS, ext4, and MTP are `Unlimited`; OS-mounted SMB and unrecognized formats are `Unknown`. The kind → cap map is the single source of truth.
- The guard blocks ONLY when certain. `Unknown`/`Unlimited` never block, so it can't raise a false alarm (a false block is worse than the old mid-copy failure — it would stop a copy that would have succeeded). exFAT, the common big-USB format, deliberately stays uncapped.
- Detection via macOS `statfs.f_fstypename` / Linux `/proc/mounts`. The gate (`validate_file_sizes_for_filesystem`) runs alongside the free-space check in the local-FS copy path and the cross-FS move-staging path; same-FS moves rename in place and skip it.
- New `WriteOperationError::FilesTooLargeForFilesystem` variant carries up to 10 offenders (name + size, largest first) plus the true total; the error dialog lists them with an "and N more" line and names FAT32 in plain language.
- Follow-ups (scoped, not in this change): SMB backing-filesystem detection (a `smb2`-crate `FileFsAttributeInformation` query), the volume-picker filesystem display, and translating the 6 new strings across the non-English locales.

Author: vdavid

apps/desktop/src-tauri/src/file_system/filesystem_kind.rs

@@ -0,0 +1,241 @@
+//! Filesystem identity and the per-file size limit derived from it.
+//!
+//! Two deliberately separate axes:
+//! - [`FilesystemKind`]: WHAT the destination filesystem is (a fact). Drives the
+//!   volume-picker label and any logic that keys off the format.
+//! - [`MaxFileSize`]: whether the filesystem caps per-file size, derived purely
+//!   from the kind. The oversized-file write guard reads this; `Unknown` and
+//!   `Unlimited` never block, only `Limited` does.
+//!
+//! The kind → limit map (`FilesystemKind::max_file_size`) is the single source
+//! of truth: the write guard, the volume DTO, and any future caller all read it.
+//!
+//! The pure logic (the enums, `from_raw_type`, the map) has no platform deps and
+//! is unit-tested directly. `detect_filesystem_for_path` is the thin
+//! platform-specific wiring that resolves a path to its OS filesystem-type
+//! string and feeds it in.
+
+use serde::{Deserialize, Serialize};
+
+/// FAT32's hard per-file ceiling: 4 GiB minus one byte, the largest value a
+/// 32-bit byte-count field can hold. A file of exactly 4 GiB does not fit.
+pub const FAT32_MAX_FILE_SIZE: u64 = u32::MAX as u64; // 4_294_967_295
+
+/// What a destination filesystem is. A factual classification used for the
+/// volume-picker label and to derive the per-file size limit. `Other` carries
+/// no detail of its own; the raw OS type string travels alongside in
+/// [`FilesystemInfo::raw_type`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, specta::Type)]
+#[serde(rename_all = "snake_case")]
+pub enum FilesystemKind {
+    Apfs,
+    HfsPlus,
+    Ext4,
+    Btrfs,
+    Xfs,
+    Zfs,
+    Ntfs,
+    ExFat,
+    /// FAT32 (and FAT16): the only common format with a hard 4 GiB per-file cap.
+    Fat32,
+    /// SMB share whose backing filesystem we can't see (an OS-mounted
+    /// `smbfs`/`cifs` mount). Direct smb2 sessions could later resolve the real
+    /// backing format; until then this stays `Unknown` for the size guard.
+    Smb,
+    /// MTP device. No queryable POSIX filesystem; large files stream fine.
+    Mtp,
+    /// Recognized nothing. The raw type string is kept in `FilesystemInfo` for
+    /// display and diagnostics.
+    Other,
+}
+
+impl FilesystemKind {
+    /// Classifies a raw filesystem-type string from macOS `statfs.f_fstypename`,
+    /// Linux `/proc/mounts`, or an SMB server's reported `FileSystemName`.
+    /// Case-insensitive. Unrecognized strings become [`FilesystemKind::Other`].
+    pub fn from_raw_type(raw: &str) -> Self {
+        match raw.to_ascii_lowercase().as_str() {
+            "apfs" => Self::Apfs,
+            "hfs" | "hfsplus" | "hfs+" => Self::HfsPlus,
+            "ext4" | "ext3" | "ext2" => Self::Ext4,
+            "btrfs" => Self::Btrfs,
+            "xfs" => Self::Xfs,
+            "zfs" => Self::Zfs,
+            "ntfs" | "ntfs3" | "ufsd_ntfs" => Self::Ntfs,
+            "exfat" | "fuse.exfat" => Self::ExFat,
+            // macOS reports both FAT16 and FAT32 as "msdos"; Linux as "vfat".
+            // Both carry the 4 GiB cap, so the safe number covers either.
+            "msdos" | "vfat" | "fat" | "fat32" | "fat16" => Self::Fat32,
+            "smbfs" | "cifs" => Self::Smb,
+            _ => Self::Other,
+        }
+    }
+
+    /// The largest single file this filesystem accepts. The single source of
+    /// truth for the oversized-file write guard.
+    ///
+    /// Only [`FilesystemKind::Fat32`] is `Limited`. Modern formats (and MTP) are
+    /// `Unlimited`; formats we can't see through (`Smb`, `Other`) are `Unknown`,
+    /// which the guard treats as "don't block" so it never raises a false alarm.
+    pub fn max_file_size(self) -> MaxFileSize {
+        match self {
+            Self::Fat32 => MaxFileSize::Limited {
+                bytes: FAT32_MAX_FILE_SIZE,
+            },
+            Self::Apfs
+            | Self::HfsPlus
+            | Self::Ext4
+            | Self::Btrfs
+            | Self::Xfs
+            | Self::Zfs
+            | Self::Ntfs
+            | Self::ExFat
+            | Self::Mtp => MaxFileSize::Unlimited,
+            Self::Smb | Self::Other => MaxFileSize::Unknown,
+        }
+    }
+}
+
+/// The largest single file a filesystem accepts. Derived from [`FilesystemKind`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, specta::Type)]
+#[serde(tag = "type", rename_all = "snake_case", rename_all_fields = "camelCase")]
+pub enum MaxFileSize {
+    /// A hard per-file ceiling in bytes (FAT32). A larger file is rejected.
+    Limited { bytes: u64 },
+    /// No practical per-file limit (APFS, ext4, NTFS, exFAT, MTP, ...).
+    Unlimited,
+    /// The limit couldn't be determined. The write guard treats this as
+    /// "don't block".
+    Unknown,
+}
+
+/// A destination filesystem's identity plus the bits the frontend needs to show
+/// it. Rides on the volume DTO (volume picker) and on the oversized-file error.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, specta::Type)]
+#[serde(rename_all = "camelCase")]
+pub struct FilesystemInfo {
+    pub kind: FilesystemKind,
+    /// Raw type string as reported by the OS (`statfs`/mounts) or an SMB server,
+    /// for display fallback on [`FilesystemKind::Other`] and for diagnostics.
+    pub raw_type: Option<String>,
+    /// The largest single file this filesystem accepts, in bytes. `None` means
+    /// no known limit (or unknown), so the picker can show "max 4 GB per file"
+    /// only when a real cap exists.
+    pub max_file_size_bytes: Option<u64>,
+}
+
+impl FilesystemInfo {
+    /// Builds from a known kind plus the raw type string it came from.
+    pub fn new(kind: FilesystemKind, raw_type: Option<String>) -> Self {
+        let max_file_size_bytes = match kind.max_file_size() {
+            MaxFileSize::Limited { bytes } => Some(bytes),
+            MaxFileSize::Unlimited | MaxFileSize::Unknown => None,
+        };
+        Self {
+            kind,
+            raw_type,
+            max_file_size_bytes,
+        }
+    }
+
+    /// Builds from a raw OS filesystem-type string (the common path). `None`
+    /// classifies as [`FilesystemKind::Other`].
+    pub fn from_raw_type(raw_type: Option<String>) -> Self {
+        let kind = raw_type
+            .as_deref()
+            .map(FilesystemKind::from_raw_type)
+            .unwrap_or(FilesystemKind::Other);
+        Self::new(kind, raw_type)
+    }
+}
+
+/// Detects the filesystem at `path` by resolving its mount and reading the OS
+/// filesystem-type string, then classifying it.
+///
+/// Returns [`FilesystemKind::Other`] / [`MaxFileSize::Unknown`] when the type
+/// can't be resolved, so the write guard never blocks on a guess.
+///
+/// macOS resolves via `statfs.f_fstypename`; other Unix via `/proc/mounts`.
+/// The single `statfs` is fast on local mounts (the only ones that reach the
+/// local-FS copy/move path); a hung network mount would already have stalled the
+/// preceding free-space query on the same destination.
+#[cfg(target_os = "macos")]
+pub fn detect_filesystem_for_path(path: &std::path::Path) -> FilesystemInfo {
+    let raw = crate::volumes::get_mount_point(&path.to_string_lossy()).map(|(_, fs_type)| fs_type);
+    FilesystemInfo::from_raw_type(raw)
+}
+
+#[cfg(target_os = "linux")]
+pub fn detect_filesystem_for_path(path: &std::path::Path) -> FilesystemInfo {
+    let raw = crate::file_system::linux_mounts::fs_type_for_path(path);
+    FilesystemInfo::from_raw_type(raw)
+}
+
+#[cfg(not(any(target_os = "macos", target_os = "linux")))]
+pub fn detect_filesystem_for_path(_path: &std::path::Path) -> FilesystemInfo {
+    FilesystemInfo::from_raw_type(None)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn classifies_known_raw_types_case_insensitively() {
+        assert_eq!(FilesystemKind::from_raw_type("apfs"), FilesystemKind::Apfs);
+        assert_eq!(FilesystemKind::from_raw_type("APFS"), FilesystemKind::Apfs);
+        assert_eq!(FilesystemKind::from_raw_type("msdos"), FilesystemKind::Fat32);
+        assert_eq!(FilesystemKind::from_raw_type("vfat"), FilesystemKind::Fat32);
+        assert_eq!(FilesystemKind::from_raw_type("exfat"), FilesystemKind::ExFat);
+        assert_eq!(FilesystemKind::from_raw_type("ntfs"), FilesystemKind::Ntfs);
+        assert_eq!(FilesystemKind::from_raw_type("smbfs"), FilesystemKind::Smb);
+        assert_eq!(FilesystemKind::from_raw_type("cifs"), FilesystemKind::Smb);
+    }
+
+    #[test]
+    fn unrecognized_raw_type_is_other() {
+        assert_eq!(FilesystemKind::from_raw_type("zalgofs"), FilesystemKind::Other);
+        assert_eq!(FilesystemKind::from_raw_type(""), FilesystemKind::Other);
+    }
+
+    #[test]
+    fn only_fat_is_limited_exfat_is_not() {
+        // The load-bearing distinction: exFAT (the common big-USB format) must
+        // NOT be capped, only FAT32.
+        assert_eq!(
+            FilesystemKind::Fat32.max_file_size(),
+            MaxFileSize::Limited {
+                bytes: FAT32_MAX_FILE_SIZE
+            }
+        );
+        assert_eq!(FilesystemKind::ExFat.max_file_size(), MaxFileSize::Unlimited);
+        assert_eq!(FilesystemKind::Ntfs.max_file_size(), MaxFileSize::Unlimited);
+        assert_eq!(FilesystemKind::Apfs.max_file_size(), MaxFileSize::Unlimited);
+        assert_eq!(FilesystemKind::Mtp.max_file_size(), MaxFileSize::Unlimited);
+    }
+
+    #[test]
+    fn unseeable_filesystems_are_unknown_not_blocked() {
+        assert_eq!(FilesystemKind::Smb.max_file_size(), MaxFileSize::Unknown);
+        assert_eq!(FilesystemKind::Other.max_file_size(), MaxFileSize::Unknown);
+    }
+
+    #[test]
+    fn fat32_cap_is_four_gib_minus_one() {
+        // A file of exactly 4 GiB must NOT fit; one byte under must.
+        assert_eq!(FAT32_MAX_FILE_SIZE, 4 * 1024 * 1024 * 1024 - 1);
+    }
+
+    #[test]
+    fn info_exposes_cap_only_for_limited_filesystems() {
+        assert_eq!(
+            FilesystemInfo::from_raw_type(Some("msdos".to_string())).max_file_size_bytes,
+            Some(FAT32_MAX_FILE_SIZE)
+        );
+        assert_eq!(
+            FilesystemInfo::from_raw_type(Some("exfat".to_string())).max_file_size_bytes,
+            None
+        );
+        assert_eq!(FilesystemInfo::from_raw_type(None).kind, FilesystemKind::Other);
+    }
+}

apps/desktop/src-tauri/src/file_system/mod.rs

@@ -1,6 +1,7 @@
 //! File system module - operations, watchers, volumes, and providers.
 
 pub mod cloud_actions;
+pub mod filesystem_kind;
 pub mod git;
 #[cfg(target_os = "linux")]
 pub(crate) mod linux_mounts;

apps/desktop/src-tauri/src/file_system/write_operations/DETAILS.md

@@ -243,6 +243,9 @@ Drives "disable Eject while an op reads from / writes to this device" so a disco
 
 ## Key decisions (shared)
 
+**Decision**: Copy and cross-FS move pre-flight a destination per-file-size limit (FAT32's 4 GiB cap) right after the scan, before the first byte. `validation::validate_file_sizes_for_filesystem` classifies the destination via `crate::file_system::filesystem_kind` (macOS `statfs.f_fstypename` / Linux `/proc/mounts` → `FilesystemKind` → `MaxFileSize`) and, only when the cap is `Limited`, fails the whole operation with `WriteOperationError::FilesTooLargeForFilesystem` (up to 10 offenders, largest first, plus the true count).
+**Why**: A FAT32 USB stick silently failed a 5 GB copy ~4 GB in. The gate is all-or-nothing and runs alongside the free-space check (`copy/mod.rs`, `move_op.rs::move_with_staging`). It blocks **only** when certain: `Unlimited` (APFS/exFAT/NTFS/ext4/MTP) and `Unknown` (OS-mounted SMB, unrecognized) never block, so a false positive — worse than the mid-copy failure because it stops a copy that would have succeeded — can't happen. **exFAT must stay `Unlimited`** (it's the common big-USB format with no 4 GiB cap); only FAT32 (`msdos`/`vfat`) is `Limited`. Same-FS moves rename in place and never reach the gate. The kind → cap map in `filesystem_kind::FilesystemKind::max_file_size` is the single source of truth (the write guard, the error prose, and any future volume-picker display all read it). SMB FileSystemName detection (a `smb2`-crate `FileFsAttributeInformation` query) and the volume-picker filesystem display are scoped follow-ups.
+
 **Decision**: Every scan reports **two** byte totals — `total_bytes` (write footprint, un-dedup'd) and `dedup_bytes` (`du`-equivalent, each inode once). Delete consumes `dedup_bytes`; copy/move consume `total_bytes`; the Copy dialog shows both.
 **Why**: A hardlink contributes differently to the two operations. **Delete** frees an inode only when its last link is removed, so the bytes-freed number is the dedup'd one — counting every link would claim to free 80 GB when only 60 GB (cargo `target/`) actually frees. **Copy/move** materialize every hardlink as an independent file at the destination (hardlinks don't survive a cross-volume copy, and even a same-FS `cp` doesn't relink), so the bytes-written number — and the disk-space reservation — is the full write footprint. The earlier single-`total_bytes`-is-dedup'd design got delete right but silently regressed copy: the space check under-reserved (risking ENOSPC mid-copy) and the bar hit 100% early. Now `walk_dir_recursive` / `walk_cached_entries` / `scan_volume_recursive` / `LocalPosixVolume::scan_for_copy` / `scan_subtree_with_oracle` all track both, using a `seen_inodes: HashSet<u64>` (mirrors `indexing/scanner.rs`, `nlink == 1` fast path, operation-scoped across source roots; **Unix-only**, where non-Unix has no `nlink()` so `dedup_bytes == total_bytes`). Volume backends populate `FileEntry::inode` only for `LocalPosixVolume` files with `nlink > 1` (MTP/SMB/InMemory leave it `None`, so dedup is a no-op and the two totals are equal). The **scan-phase** progress bar reports the dedup'd running total (it's compared against the indexer's inode-dedup'd `dir_stats` estimate, so reporting the write footprint would overshoot 100% on hardlink trees). The **delete** active phase sums per-entry `progress_bytes`/`VolumeDeleteEntry::progress_bytes` (= dedup'd) against the `dedup_bytes` denominator. The **copy** active phase credits full per-file `size` against the `total_bytes` denominator (no chunk scaling). The Copy dialog surfaces the gap with a one-line note ("X will be written; source is Y; the extra is hardlinked files…") via `dedup_bytes_total` on the scan-preview events — copy-only, since a same-FS move writes nothing. Pinned by `delete/hardlink_progress_tests.rs`, `delete/volume_hardlink_progress_tests.rs`, `transfer/hardlink_progress_tests.rs::copy_counts_write_footprint_for_hardlinks`, `scan.rs::tests::walker_dedupes_*`, `local_posix_test::test_scan_for_copy_dedupes_hardlinks_for_source_size_only`, and `transfer-dialog-utils.test.ts::shouldShowHardlinkNote`.
 

apps/desktop/src-tauri/src/file_system/write_operations/transfer/copy/mod.rs

@@ -25,7 +25,7 @@ use super::super::types::{
     WriteOperationConfig, WriteOperationError, WriteOperationPhase, WriteOperationType, WriteProgressEvent,
     WriteSourceItemDoneEvent,
 };
-use super::super::validation::validate_disk_space;
+use super::super::validation::{validate_disk_space, validate_file_sizes_for_filesystem};
 use super::transfer_driver::{DriverConfig, PostLoopIntent, TransferOutcome, drive_transfer_serial_sync};
 
 mod rollback;
@@ -184,6 +184,11 @@ pub(in crate::file_system::write_operations) fn copy_files_with_progress_inner(
         operation_id
     );
 
+    // Pre-flight filesystem-limit check: block before writing a byte if any file
+    // is too large for the destination filesystem (FAT32's 4 GiB cap). No-op for
+    // filesystems with no known limit.
+    validate_file_sizes_for_filesystem(destination, &scan_result.files)?;
+
     // Phase 2: Copy files in sorted order with rollback support
     let mut transaction = CopyTransaction::new();
     let mut apply_to_all_resolution = ApplyToAll::default();

apps/desktop/src-tauri/src/file_system/write_operations/transfer/move_op.rs

@@ -18,7 +18,7 @@ use super::super::types::{
     WriteOperationConfig, WriteOperationError, WriteOperationPhase, WriteOperationType, WriteProgressEvent,
     WriteSourceItemDoneEvent,
 };
-use super::super::validation::{is_same_filesystem, path_exists_or_is_symlink};
+use super::super::validation::{is_same_filesystem, path_exists_or_is_symlink, validate_file_sizes_for_filesystem};
 use super::copy::copy_single_item;
 
 // ============================================================================
@@ -482,6 +482,12 @@ fn move_with_staging(
         )?
     };
 
+    // Pre-flight filesystem-limit check: a cross-FS move stages a full copy, so
+    // the destination's per-file cap (FAT32's 4 GiB) applies. Block before
+    // creating the staging dir or writing a byte. No-op for filesystems with no
+    // known limit. (Same-FS moves rename in place and never reach here.)
+    validate_file_sizes_for_filesystem(destination, &scan_result.files)?;
+
     // Create staging directory
     let staging_dir = destination.join(format!(".cmdr-staging-{}", operation_id));
     fs::create_dir(&staging_dir).map_err(|e| WriteOperationError::IoError {

apps/desktop/src-tauri/src/file_system/write_operations/types.rs

@@ -429,13 +429,37 @@ pub enum WriteOperationError {
     DeletePending {
         path: String,
     },
+    /// One or more files exceed the destination filesystem's per-file size
+    /// limit (FAT32's 4 GiB cap). Detected during the pre-copy scan, before any
+    /// bytes are written, so the whole operation is blocked all-or-nothing
+    /// rather than failing partway through.
+    FilesTooLargeForFilesystem {
+        /// The destination filesystem, so the message can name it ("FAT32").
+        filesystem: crate::file_system::filesystem_kind::FilesystemKind,
+        /// The per-file ceiling in bytes (FAT32: 4 GiB − 1).
+        max_size: u64,
+        /// Up to 10 offending files (name + size), largest first.
+        files: Vec<OversizedFile>,
+        /// Total number of offending files (may exceed `files.len()`).
+        total_count: usize,
+    },
     /// Catch-all for genuinely unexpected IO errors.
     IoError {
         path: String,
         message: String,
     },
 }
 
+/// A file that exceeds the destination filesystem's per-file size limit.
+/// Carried by [`WriteOperationError::FilesTooLargeForFilesystem`] so the dialog
+/// can list the offenders.
+#[derive(Debug, Clone, Serialize, Deserialize, specta::Type)]
+#[serde(rename_all = "camelCase")]
+pub struct OversizedFile {
+    pub name: String,
+    pub size: u64,
+}
+
 // ============================================================================
 // Result types
 // ============================================================================