What causes "IO error, volume may be offline: {}" in spacedriveapp/spacedrive?

Check system logs (dmesg or Event Viewer) for device or filesystem errors on that volume

IO error, volume may be offline: {}

Error message

IO error, volume may be offline: {}

What it means

The volume backend hit a non-NotFound IO error while checking path existence: the volume appears mounted but its storage returned an error. Distinct from NotMounted - this points at unhealthy or slow storage such as a failing disk, a stalled network share, or a hung cloud driver. The handler warn-logs the path and the IO error, then aborts verification for that path.

Source

Thrown at core/src/ops/indexing/change_detection/handler.rs:85

		match backend.exists(path).await {
			Ok(exists) => Ok(exists),
			Err(VolumeError::NotMounted(_)) => {
				tracing::warn!(
					"Volume not mounted when checking path existence: {}",
					path.display()
				);
				Err(anyhow::anyhow!(
					"Volume not mounted, cannot verify path existence"
				))
			}
			Err(VolumeError::Io(ref e)) if e.kind() == std::io::ErrorKind::NotFound => Ok(false),
			Err(VolumeError::Io(io_err)) => {
				tracing::warn!(
					"IO error when checking path existence for {}: {}",
					path.display(),
					io_err
				);
				Err(anyhow::anyhow!(
					"IO error, volume may be offline: {}",
					io_err
				))
			}
			Err(e) => {
				tracing::warn!(
					"Volume error when checking path existence for {}: {}",
					path.display(),
					e
				);
				Err(e.into())
			}
		}
	} else {
		match tokio::fs::try_exists(path).await {
			Ok(exists) => Ok(exists),
			Err(e) => {
				tracing::warn!(

View on GitHub (pinned to 6dfeccf211)

Solutions

Check system logs (dmesg or Event Viewer) for device or filesystem errors on that volume
Reconnect or remount the volume and retry the indexing job
For network volumes, verify connectivity and credentials to the server
Run storage health diagnostics if errors persist on one device

Defensive patterns

Strategy: retry

Try / catch

// Volume IO errors are often transient (network shares recovering).
let mut attempt = 0;
loop {
    attempt += 1;
    match backend.exists(path).await {
        Ok(exists) => break Ok(exists),
        Err(VolumeError::Io(_)) if attempt < 3 => {
            tokio::time::sleep(std::time::Duration::from_secs(2 * attempt as u64)).await;
        }
        Err(e) => break Err(e.into()),
    }
}

Prevention

Monitor disk health and replace failing volumes
Keep network shares reachable during indexing windows
Treat repeated IO errors on one volume as a hardware signal

When it happens

Trigger: Failing HDD or USB sectors returning EIO; NFS or SMB timeout and stale handles; cloud-sync driver hangs; permission errors at the volume root.

Common situations: Aging external drives, unstable Wi-Fi behind network shares, oversubscribed cloud sync clients.

Related errors

AI-assisted analysis of spacedriveapp/spacedrive@6dfeccf211 (2026-08-16). Data as JSON: /api/errors/afbac2b2fc60fb74. Report an issue: GitHub.