iCloud Deleted My Documents Folder: A Lesson in Sync vs Backup
iCloud deleted my entire Documents folder. 214,000 files, gone. Time Machine couldn't help—it had only backed up empty stubs. This is the story of what went wrong and the file storage philosophy I developed afterward.
The Disaster
I was reorganizing my Documents folder with shell commands. Nothing exotic—mv operations to restructure directories. At some point, iCloud's sync engine got confused. Operations were happening faster than it could track. Conflicts emerged, and its resolution strategy was apparently "delete everything."
The deletions propagated to all my devices before I noticed. By the time I checked, every Mac, iPhone, and iPad agreed: the folder was empty.
No problem, I thought. Time Machine runs hourly. I'll just restore.
I opened Time Machine, navigated to Documents, and found... empty folders. Placeholder files. Stubs.
The False Safety Net
Here's what I didn't understand about "Optimize Mac Storage": when enabled, iCloud replaces local files with lightweight stubs. The actual data lives only in the cloud. Your Mac shows the files, you can see their names and sizes, but the bytes aren't there.
Time Machine backs up what's on disk. If what's on disk is stubs, that's what gets backed up. Stubs.
So my "backup" was a perfect historical record of empty placeholder files. Months of backups, all useless.
What I Didn't Understand About Sync
Sync is a distributed systems problem. Multiple devices, each making changes, trying to converge on a consistent state. This is genuinely hard—entire engineering teams work on getting it right.
All consumer cloud drives hide this complexity. There's no "conflict detected" dialog, no merge interface, no decision points. It just works, magically, until it doesn't. The difference is how gracefully they fail. Dropbox tends to create "conflicted copy" files you can sort out later. Google Drive has version history you can recover from. iCloud's failure mode, in my experience, was silent deletion.
The design assumption: humans making changes at human pace. Open a document, edit, save, close. One file, one device, seconds or minutes between operations. The sync system has time to propagate changes, detect conflicts, resolve them quietly.
What I did: hundreds of file operations per second, restructuring entire directory trees, programmatically. The sync system couldn't keep up. Race conditions emerged. Somewhere in the chaos, iCloud decided my files should be deleted.
Consumer cloud drives are not designed for programmatic file operations. This isn't a bug—it's a fundamental mismatch between the use case and the tool.
First Principles: Backup vs Sync
Once I understood what happened, I thought about file storage from first principles.
Backup:
- One direction: local → remote
- You control when it happens
- Versioned: you can restore previous states
- No conflicts possible
- A copy exists even if the original is destroyed
Sync:
- Bidirectional: changes flow both ways
- Always-on: happens automatically
- Current state only (maybe some version history)
- Conflicts possible, must be resolved somehow
- Deletions propagate—a feature, not a bug
Sync and backup solve different problems. Sync gives you access to files from multiple devices. Backup protects you from data loss.
iCloud tries to be both and does neither well. It syncs your files but isn't a backup—deletions propagate. Combined with Optimize Storage, your local "backup" solution (Time Machine) becomes useless.
The New Stack
I turned off iCloud Desktop & Documents sync. Files live locally now.
| Layer | Tool | Purpose |
|---|---|---|
| Storage | Local ~/files |
Full control, no sync interference |
| Local backup | Time Machine → external SSD | Fast restore, point-in-time |
| Offsite backup | Backblaze | Disaster recovery, version history |
| Sync | On-demand only | Intentional sharing when needed |
The key shift: sync is not the default. Files live locally. Time Machine backs them up (actual files, not stubs). Backblaze provides offsite redundancy.
When I need to share something or access it from another device, I intentionally put it somewhere synced. Then I remove it. Sync is a tool I use deliberately, not an ambient background process.
One Exception
No philosophy survives contact with reality unchanged.
My Obsidian vault still lives in iCloud. I need it on my phone.
But I understand the trade-off now:
- Human-paced markdown edits only—no scripts touching this folder
- "Keep downloaded" enabled so Time Machine gets real files
- Git provides additional version history
- If iCloud corrupts it, I have backups
It's an informed risk, not blind trust.
The Lesson
Don't pay complexity tax for features you don't use.
Always-on bidirectional sync is complex. It solves the problem of "I need my files on multiple devices, and changes should propagate instantly." If you don't have that problem, you're paying the complexity cost—subtle failure modes, propagating deletions, conflicts—for nothing.
Most of my files don't need to be on every device. They need to not disappear. That's a backup problem, not a sync problem.
I eventually recovered the files by reverse engineering iCloud's API. But I'd rather not need to do that again.