iOS iCloud Drive Synchronization Deep Dive

Today, I was pondering a feature idea for my macOS/iOS app, Actions For Obsidian. That idea is loosely related to iCloud Drive. But ever since AFO’s release a few years back, I got dozens of support requests from folks who ran into issues while attempting to use iCloud Drive as means of synchronizing their Obsidian vaults between their devices.

Usually, my one-word answer to these questions is “Don’t.", accompanied by a link to a FAQ entry that I wrote a while back: “Can I use iCloud Sync with Obsidian and Actions for Obsidian?" (Spoiler: Yes, but it’ll be painful at one point or the other …or several.)

I had a pretty good mental model of iCloud Drive’s behavior built up already, but as I was thinking about that aforementioned feature idea, I figured that Claude Opus 4.1’s “research mode” might speed up the process a bit. So I tasked it to dive deep into researching how iCloud Drive synchronization works, particularly focusing on iOS behavior and specific scenarios with Obsidian vaults and the “Keep Downloaded” feature.

The resulting doc is what you’ll find below. Enjoy. #sharingIsCaring


iOS iCloud Drive Synchronization Deep Dive

Apple’s iCloud Drive synchronization on iOS operates as a system-controlled process that prioritizes device performance and battery life over real-time sync, fundamentally changing how third-party apps like Obsidian must approach data synchronization. Unlike traditional file sync services, iOS maintains strict control over when, how, and under what conditions synchronization occurs, creating both powerful integration opportunities and significant technical challenges for developers and users.

The core architectural principle revealed through Apple’s official documentation is that applications cannot force synchronization1 - the iOS system decides all sync timing based on complex algorithms that consider network conditions, battery state, thermal management, and learned user behavior patterns23. This system-first approach means that apps like Obsidian must work within iOS’s scheduling constraints rather than implementing direct sync control.

System-controlled sync architecture governs all operations

Apple’s iCloud Drive uses a sophisticated two-stage synchronization process where files move from app containers to system-managed directories, then propagate to iCloud servers “as soon as possible”4 - but timing remains entirely system-controlled. All file operations must use NSFileCoordinator objects to prevent conflicts between applications and the sync daemon, creating a coordination layer that acts as a locking mechanism567.

The system implements intelligent throttling mechanisms designed to protect both device resources and server infrastructure. CloudKit throttles requests when it determines the request rate is too high, with 30-second minimum intervals between rapid operations567. This throttling serves as protection against overwhelming system resources and maintains server stability.

File coordination requirements create significant technical complexity for developers. Every file access requires coordination to prevent race conditions, and file presenters are “very expensive objects” requiring extensive inter-process communication8. Context switches occur between the reading process, presenting process, and file coordination daemon, risking depletion of system resources if too many presenters are registered.

Synchronization triggers operate on multiple system levels

Automatic triggers include app foreground events, network state changes, system resource availability, and device wake cycles. When an app comes to the foreground, especially on macOS, sync often triggers immediately9. Network connectivity changes - particularly switching from cellular to WiFi - initiate sync attempts. The system also monitors storage conditions, pausing sync when iCloud storage is full or device storage is constrained1011.

Manual sync triggers are limited but exist through specific user actions. Users can force sync by toggling iCloud Drive settings off and on, signing out and back into iCloud accounts, or using app-specific refresh mechanisms like pull-to-refresh in Contacts and Calendar apps1011. However, these methods don’t guarantee immediate sync - they merely request that the system prioritize sync operations.

Background app refresh plays a critical enabling role for sync operations. Apps must be granted Background App Refresh permission, and iOS uses machine learning to determine optimal sync timing based on user behavior patterns, available system resources, network quality, battery level, and time-of-day patterns121314. The system can take “seven days for Apple’s on-device ML to pick up that the user really wants to use the app,"15 affecting sync frequency during this learning period.

Timing patterns follow intelligent resource management

Synchronization frequency varies dramatically based on system conditions rather than following fixed intervals. Apple’s documentation explicitly states that “CloudKit synchronization isn’t real time” and timing is “as-designed to better balance the use of system resources and achieve the best overall user experience."16 The system implements no guaranteed timing - sync operates on an opportunistic basis when conditions are favorable171.

Priority scheduling follows a clear hierarchy: foreground app operations receive highest priority, followed by critical system functions, user-initiated sync requests, scheduled background sync tasks, and finally opportunistic background sync. iOS uses BGTaskScheduler (iOS 13+) to replace legacy background fetch with more sophisticated scheduling based on device usage patterns learned over time181920.

Background execution limitations significantly impact sync behavior. Background App Refresh provides only limited execution time - typically 30 seconds for BGAppRefreshTask and longer durations for BGProcessingTask, but only when external power is available for heavy operations2122. Apps cannot force specific sync intervals and must work within iOS scheduling constraints where background execution is “cooperative” and can be terminated at any time.

App-specific behavior creates unique integration challenges

Obsidian’s vault synchronization exemplifies the challenges third-party apps face with iCloud Drive integration. User reports consistently describe unidirectional sync failures where “creating new notes in macOS syncs immediately to iOS, but editing notes in iOS doesn’t sync back to macOS."232425 Files frequently get “stuck uploading” with cloud icons showing indefinitely, and the app lacks native conflict resolution, leading to silent overwrites when notes are edited on multiple devices while offline.

Developer implementation challenges stem from iCloud’s low-level API requirements. Developers report that “the iCloud API is too low level,” requiring extensive code for basic operations with no single function for putting files into or removing them from iCloud26. The asynchronous, cooperative, lock-based nature creates “implications that are often not easy to grasp,"27 leading many developers to prefer alternatives like Dropbox for reliability.

Document-based versus file-based sync creates different user experiences. Document-based apps using NSDocument/UIDocument protocols benefit from automatic conflict resolution, while file-based sync (like Obsidian) relies on basic iCloud Drive file synchronization without built-in conflict handling28. Advanced apps must implement custom conflict resolution UIs to match user expectations29.

Sync interruption patterns follow predictable system states

Network-dependent behavior shows strong WiFi preference with cellular serving as a heavily throttled fallback. Even with cellular enabled, iOS implements intelligent throttling where sync only occurs over cellular when WiFi hasn’t been available for extended periods3031. Low Data Mode specifically pauses iCloud sync operations3233, and users report that iCloud Drive downloads often fail over cellular connections even when uploads work34.

Power management creates definitive sync boundaries. Low Power Mode automatically pauses all iCloud sync operations when battery drops below 20% and remains paused even when the device is charged until manually disabled353637. iOS displays “Optimizing Battery Power” messages when pausing sync to preserve battery life, and thermal management pauses operations when devices overheat with “Device Needs to Cool Down” messages38.

Storage conditions create hard stops for synchronization. Sync completely halts when iCloud storage quota is exceeded, and iOS pauses sync when device storage drops below critical thresholds3940. The system displays specific status messages including “Low Data Mode,” “Poor Network Connection,” and “Device Needs to Cool Down” to communicate sync pause reasons41.

File prioritization follows system-managed algorithms

“Keep Downloaded” versus normal cloud storage creates two distinct sync behaviors. Files marked “Keep Downloaded” remain local even when storage optimization is active, while normal cloud storage uses on-demand download where files exist as placeholders until accessed4243. The system provides visual indicators through cloud/download status icons, and users can manually set Keep Downloaded status via context menus.

Sync prioritization algorithms aren’t fully documented by Apple, but research reveals patterns: the system prioritizes based on system resources first, then user experience considerations, data integrity requirements, and server load management. Large files are often deprioritized in favor of smaller, more critical data, and iOS may selectively sync metadata before file contents when storage is constrained.

Background versus foreground sync behavior creates dramatically different user experiences. Foreground sync typically works “within seconds” with immediate updates, while background sync can take “minutes or even up to an hour” depending on iOS scheduling decisions44. macOS apps sync continuously while running, but iOS apps depend entirely on system wake-ups that follow learned usage patterns.

Network and battery conditions shape sync behavior

WiFi versus cellular sync patterns show strong system bias toward WiFi connections. Users must explicitly enable cellular data for iCloud Drive in Settings > Cellular > iCloud Drive45464748, but even with cellular enabled, iOS implements aggressive throttling. The “Documents & Sync” system service can consume substantial cellular data (1-8GB reported cases)4950, leading iOS to discourage cellular sync through power management restrictions.

Battery state management creates multiple intervention points. Beyond Low Power Mode’s complete sync pause, iOS implements “Optimizing System Performance” states that pause sync to prioritize foreground tasks51. The system preferentially schedules heavy sync operations when devices are connected to power, with iCloud Photos specifically requiring power connection, WiFi, and locked screen for backup operations52.

Thermal management adds another layer of sync control where operations pause automatically when devices overheat. System-level thermal protection takes priority over sync completion, and users report that sync issues can persist even after cooling if the thermal event triggered system resource reallocation.

Background app refresh fundamentally enables sync functionality

Background execution architecture through BGTaskScheduler provides the foundation for non-foreground sync operations. The system grants limited execution time with tasks running when iOS determines optimal conditions exist: device charging, stable WiFi, learned usage patterns, and available system resources535455. Machine learning algorithms determine which apps deserve background execution time, with new devices requiring iOS to “relearn” app usage patterns56.

App-specific background sync behavior varies significantly between foreground and background states. Active apps can immediately respond to file changes and trigger downloads, while backgrounded apps rely on silent push notifications and Background App Refresh scheduling57. Suspended apps cannot perform any sync operations, and force-quit apps will not receive background wake-ups at all58.

Background sync limitations create user experience challenges where sync can appear unreliable or delayed. iOS provides “opportunistic” scheduling rather than guaranteed execution, and background tasks are treated as “low priority” with delivery not guaranteed59. Some apps implement “Incremental Sync” strategies to be more energy-efficient within these constraints.

Network connectivity creates distinct behavioral patterns

WiFi versus cellular behavior differences extend beyond data usage to sync reliability and speed. WiFi connections enable full-featured sync with immediate file downloads and uploads, while cellular connections often experience partial sync where uploads succeed but downloads fail. Users report that toggling between airplane mode and cellular can sometimes restart stalled uploads, suggesting iOS manages cellular sync more conservatively.

VPN and network security impacts create additional sync complications. Some VPN configurations block iCloud traffic entirely, and network security applications may interfere with sync operations60. Enterprise MDM profiles often include restrictions that disable cloud sync6162, and corporate firewalls can selectively block iCloud synchronization traffic.

Network transition handling reveals system sophistication in managing connectivity changes. iOS automatically pauses sync during poor network conditions and resumes when connectivity improves. The system displays “Poor Network Connection” status messages and implements intelligent retry algorithms that avoid overwhelming weak connections63.

Developer documentation reveals architectural constraints

Apple’s official technical documentation emphasizes that iCloud Drive operates as a system-managed service rather than application-controlled sync. WWDC sessions explicitly state “the system decides when to synchronize data” and “there is no API for app developers to force an iCloud Drive synchronization."64 This architectural decision prioritizes overall device performance over individual app sync requirements.

File coordination requirements mandate that all iCloud operations use NSFileCoordinator objects and NSFilePresenter protocols. Apple’s Technical Note TN3162 reveals that CloudKit throttles applications when request rates are too high, with 30-second minimum intervals between rapid operations6566. These constraints protect system resources but create complexity for developers building sync-dependent applications.

Conflict resolution frameworks provide automatic handling for document-based apps but require custom implementation for file-based sync. Apple mandates that apps resolve conflicts “quietly whenever possible” and only prompt users when automatic resolution isn’t feasible676869. The system provides NSFileVersion frameworks for conflict detection but requires app-level logic for resolution70.

Common sync issues follow predictable patterns

Most frequent problems include “Syncing with iCloud Paused” errors71, files stuck “Waiting to Upload/Download,"72 partial sync where some files sync while others remain pending, and “Zero KB of XGB” upload progress displays73. Users also report missing files across devices, duplicate files with number suffixes during conflicts, and grayed-out files with exclamation mark cloud icons747576.

Diagnostic approaches range from basic connectivity checks to advanced terminal commands on macOS. Users can check sync status in Photos app status messages, monitor iCloud storage usage, verify app-specific sync settings, and test with small files to verify basic functionality. Mac power users employ terminal commands like brctl log -w --shorten for real-time sync monitoring and brctl status for container sync status777879.

Recovery strategies include both official Apple solutions and community-developed workarounds. Official methods involve device restarts, iCloud Drive setting toggles, and complete iCloud account refresh808182. Community solutions include VPN cycling, router restarts, time zone changes, and systematic network cycling routines83. Advanced users employ mass file download scripts and automated sync health checks using command-line tools8485.

Third-party app interaction reveals system limitations

Apps like Obsidian face inherent challenges working within iOS sync constraints. The vault-based file structure requires reliable bidirectional sync, but iCloud Drive’s system-controlled timing creates user experience issues where edits made on iOS devices don’t propagate reliably to other platforms86878889. Users frequently report directional sync failures and recommend keeping apps in foreground during critical sync operations.

Developer alternatives often include migrating away from iCloud Drive toward more predictable sync solutions. Many developers prefer Dropbox for its reliability and traditional file/folder approach, while others migrate to CloudKit for better control over structured data90. Third-party sync solutions like Simperium offer more predictable behavior but require custom infrastructure.

Integration best practices that emerge from developer experiences include designing UIs to gracefully handle sync delays and failures, providing manual sync triggers for user-initiated operations, implementing proper state restoration for interrupted sync processes, and educating users about iOS sync limitations and optimal usage patterns9192.

Conclusion

iCloud Drive synchronization on iOS represents a sophisticated system-managed approach that prioritizes device performance, battery life, and user experience over application-controlled real-time sync. While this creates powerful integration capabilities within Apple’s ecosystem, it fundamentally changes how developers and users must approach cloud synchronization.

The key insight is that iOS treats sync as a system service rather than an application feature, implementing intelligent scheduling, resource management, and conflict prevention that operates beyond direct application control. This approach succeeds in protecting device resources and providing generally reliable sync for most users, but creates significant challenges for applications requiring predictable, real-time synchronization behavior.

For users of apps like Obsidian, understanding these system limitations helps set appropriate expectations and develop workflows that work within iOS constraints rather than against them. The future of iOS sync will likely continue emphasizing system intelligence over application control, making adaptation to these patterns essential for both developers and users relying on iCloud Drive synchronization.


  1. Apple Developer Forums - Develop a piece of code to force iCloud Drive sync ↩︎

  2. Apple Developer - Syncing model data across a person’s devices ↩︎

  3. Snowdog - How to manage background tasks with the Task Scheduler in iOS 13? ↩︎

  4. Apple Developer - iCloud File Management ↩︎

  5. Apple Developer Forums - CloudKit error - CKErrorRequestRat… ↩︎

  6. Apple Developer - Technical Note TN2336: Handling version conflicts in the iCloud environment ↩︎

  7. Snowdog - How to manage background tasks with the Task Scheduler in iOS 13? ↩︎

  8. objc.io - Mastering the iCloud Document Store ↩︎

  9. Apple Developer Forums - CloudKit sync refresh problem when… ↩︎

  10. Apple Support - If your iCloud Contacts, Calendars, or Reminders won’t sync ↩︎

  11. Computerworld - How to fix iCloud sync in seconds ↩︎

  12. Due App Support - Background sync not working ↩︎

  13. Snowdog - How to manage background tasks with the Task Scheduler in iOS 13? ↩︎

  14. Due App Support - Background sync not working ↩︎

  15. Hacker News - Yes, the app does iOS background sync ↩︎

  16. Apple Developer Forums - Collaboration of iCloud Drive docu… ↩︎

  17. Apple Developer Forums - Develop a piece of code to force iCloud Drive sync ↩︎

  18. Andy Ibanez - Modern Backgrounds Tasks in iOS 13 ↩︎

  19. Apple Developer - BGTaskScheduler ↩︎

  20. Stack Overflow - BGTaskScheduler: Is it possible to schedule a background task inside a background task? ↩︎

  21. Apple Developer Forums - IOS Development - Background sync… ↩︎

  22. Stack Overflow - BGTaskScheduler: Is it possible to schedule a background task inside a background task? ↩︎

  23. Obsidian Forum - Obsidian won’t sync via icloud ↩︎

  24. Obsidian Forum - iCloud Drive iOS and MacOS Sync Inconsistencies - Serious ↩︎

  25. Obsidian Forum - iCloud Drive iOS and MacOS Sync Inconsistencies - Serious ↩︎

  26. Notability - Troubleshooting iCloud Sync ↩︎

  27. objc.io - Mastering the iCloud Document Store ↩︎

  28. Obsidian Forum - Understanding iCloud Sync issues ↩︎

  29. Apple Developer - Technical Note TN2336: Handling version conflicts in the iCloud environment ↩︎

  30. Apple Community - Cellular vs WiFi causing the iCloud sync… ↩︎

  31. Apple Community - iCloud Drive on cellular data network ↩︎

  32. Apple Support - Use Low Data Mode on your iPhone and iPad ↩︎

  33. Eskimo - What is Low Data Mode on iPhone and How to Turn It Off ↩︎

  34. Apple Support - If your iCloud Photos are not syncing ↩︎

  35. Apple Support - If your iCloud Photos are not syncing ↩︎

  36. Apple Support - If your iCloud Photos are not syncing ↩︎

  37. Notability - Troubleshooting iCloud Sync ↩︎

  38. Eskimo - What is Low Data Mode on iPhone and How to Turn It Off ↩︎

  39. Gbyte - Syncing with iCloud Paused: Complete Guide to Fix It ↩︎

  40. Apple Support - If your iCloud Photos are not syncing ↩︎

  41. Apple Support - If your iCloud Photos are not syncing ↩︎

  42. Apple Support - Check your iCloud Drive file and folder status on Mac ↩︎

  43. Apple Support - If your iCloud Photos are not syncing ↩︎

  44. Apple Support - If your iCloud Photos are not syncing ↩︎

  45. Apple Support - Work with folders and files in iCloud Drive ↩︎

  46. Apple Support - Work with folders and files in iCloud Drive (SA) ↩︎

  47. Due App Support - Background sync not working ↩︎

  48. Apple Support - Set up iCloud Drive on all your devices ↩︎

  49. Ask Different - On iOS, is there any way to see what the “Documents & Sync” system service is using cellular data for? ↩︎

  50. Apple Community - Why Documents & Sync use my Cellular Data… ↩︎

  51. Apple Support - If your iCloud Photos are not syncing ↩︎

  52. Macworld - iCloud vs. Wi-Fi Sync: Which does what? ↩︎

  53. Andy Ibanez - Modern Backgrounds Tasks in iOS 13 ↩︎

  54. Stack Overflow - BGTaskScheduler: Is it possible to schedule a background task inside a background task? ↩︎

  55. Snowdog - How to manage background tasks with the Task Scheduler in iOS 13? ↩︎

  56. Due App Support - Background sync not working ↩︎

  57. Due App Support - Background sync not working ↩︎

  58. Due App Support - Background sync not working ↩︎

  59. Due App Support - Background sync not working ↩︎

  60. MacRumors Forums - iCloud sync photos on battery (possible?) ↩︎

  61. Goodnotes Support - iCloud Sync issues ↩︎

  62. Notability - Troubleshooting iCloud Sync ↩︎

  63. Microsoft Community Hub - Changes to applications' backup and restore behavior on iOS/iPadOS and macOS devices ↩︎

  64. Apple Developer - Sync files to the cloud with FileProvider on macOS - WWDC21 ↩︎

  65. Apple Developer - TN3162: Understanding CloudKit throttles ↩︎

  66. Apple Developer Forums - CloudKit user ‘throttling’ ↩︎

  67. Apple Developer - Technical Note TN2336: Handling version conflicts in the iCloud environment ↩︎

  68. Apple Developer - Technical Note TN2336: Handling version conflicts in the iCloud environment ↩︎

  69. Apple Developer - Technical Note TN2336: Handling version conflicts in the iCloud environment ↩︎

  70. Apple Developer - iCloud File Management ↩︎

  71. AirDroid - Fix “Syncing With iCloud Paused” Error Within Minutes ↩︎

  72. Apple Community - iCloud Files Sync Stuck ↩︎

  73. Apple Community - iCloud sync stuck? ↩︎

  74. Apple Support - If your iCloud Photos are not syncing ↩︎

  75. Computerworld - How to fix iCloud sync in seconds ↩︎

  76. Notability - Troubleshooting iCloud Sync ↩︎

  77. Wesley de Groot - iCloud Drive Tips & Tricks ↩︎

  78. Wesley de Groot - iCloud Drive Tips & Tricks ↩︎

  79. Ask Different - iCloud Sync activity log ↩︎

  80. Apple Support - If your iCloud Contacts, Calendars, or Reminders won’t sync ↩︎

  81. Computerworld - How to fix iCloud sync in seconds ↩︎

  82. Super User - icloud drive sync stuck ↩︎

  83. Apple Community - iCloud sync and update very, very slow ↩︎

  84. Archit Chandra - A Side Effect of Storing a Git Repository in iCloud Drive ↩︎

  85. Apple Developer Forums - SwiftData iCloud sync breaks after… ↩︎

  86. Obsidian Forum - Obsidian won’t sync via icloud ↩︎

  87. Obsidian Forum - iCloud Drive iOS and MacOS Sync Inconsistencies - Serious ↩︎

  88. Obsidian Forum - iCloud Drive iOS and MacOS Sync Inconsistencies - Serious ↩︎

  89. Obsidian Forum - Sync solutions ↩︎

  90. Notability - Troubleshooting iCloud Sync ↩︎

  91. Apple Developer Forums - SwiftData iCloud sync breaks after… ↩︎

  92. Apple Developer Forums - SwiftData iCloud sync breaks after… ↩︎

Carlo Zottmann @czottmann

👋🏼 Oh hello!

Sorry to be a bother, but did you know I make quite useful Shortcuts-related macOS & iOS apps?

Check them out!