OneDrive Files On-Demand deep dive

Files On-Demand is the reason a OneDrive with two terabytes in it fits on a laptop with a 256 GB drive. It's also the reason a backup agent suddenly downloaded two terabytes overnight, why a user's "missing" file was never missing, and why a line-of-business app crashed opening a file that "was right there." The sync client overview covers how sync works; this guide goes one layer down into Files On-Demand specifically — the states, the plumbing, the policies, and the failure modes.

The three states

Every file in a synced OneDrive or SharePoint library is in one of three states, shown by the status icon in Explorer:

• Online-only (cloud icon). A placeholder exists on disk with the correct name, size, timestamps, and thumbnail, but no content. It occupies effectively zero space. Opening it triggers a download.
• Locally available (green tick, outlined). The content has been downloaded because something opened it. It stays local until the system decides to free space, at which point it can be dehydrated back to online-only.
• Always keep on this device (green tick, solid). The user or policy has pinned it; it's downloaded and won't be dehydrated automatically. This is the state for the project folder you need on a plane.

The state is per file, but the context menu lets you set it on a folder, which applies to everything beneath it and to new files that arrive there.

How the placeholder works

On Windows, Files On-Demand is built on the Cloud Files API and its filter driver (cldflt.sys). Placeholders are real NTFS files with reparse points. When an application opens a placeholder, the filter intercepts the I/O, asks the OneDrive client to fetch the content (hydration), and blocks the read until it arrives. To the application, it's just a slow file open. That transparency is the feature, and it's also the source of most of the trouble: applications don't know they're triggering downloads, and anything that reads every file — backup, indexing, antivirus on-demand scans, a "find in files" over a folder tree — hydrates the lot.

You can see the state from a command line. attrib on a synced folder shows the cloud-files attributes: O (offline / online-only), U (unpinned — locally available but eligible for dehydration), and P (pinned — always keep). A file showing neither O nor P with a U is locally cached; a file with O is a placeholder. It's the fastest way to audit what a user actually has on disk.

Dehydration happens in two ways: the user chooses Free up space on a file or folder, or Storage Sense (Settings → System → Storage) dehydrates files that haven't been opened in a configurable number of days when the disk runs low. Storage Sense's OneDrive setting is per user and off by default on many builds; it's worth enabling through policy for laptops with small drives.

Always on now

Files On-Demand was optional for years and could be turned off, which caused its own problems (a "sync everything" user on a small drive). On current Windows 11 builds with the current sync client it's always enabled and the toggle is gone. The FilesOnDemandEnabled policy still exists for older combinations, but the practical posture in 2026 is: it's on, plan around it. Users who need everything local pin the root folder.

Mac

On macOS, Files On-Demand runs on Apple's File Provider platform, which OneDrive moved to some years ago. The visible differences: the OneDrive folder lives under ~/Library/CloudStorage/OneDrive-<tenant> (with a symlink in the home folder), the states are shown with Finder's own cloud icons, and Files On-Demand can't be disabled — pinning is the only way to force content local. Finder's "Download Now" and "Remove Download" are the equivalents of hydrate and free up space. Apps that use old-style path assumptions occasionally break on the CloudStorage path; that's a Mac-specific compatibility point to test.

Policies worth knowing

Through the OneDrive ADMX templates (Group Policy or Intune settings catalog):

• FilesOnDemandEnabled — historic on/off. Leave on.
• Known Folder Move settings — Desktop, Documents, Pictures redirected into OneDrive are subject to Files On-Demand like everything else, so a user's Desktop can contain placeholders. The KFMSilentOptIn family is covered in the Known Folder Move guide.
• DehydrateSyncedTeamSites — dehydrate SharePoint libraries that were synced before Files On-Demand was enabled, to reclaim space.
• Storage Sense cloud content dehydration threshold — set through the Storage Sense policy, not OneDrive's.
• Block file downloads or restrict sync to managed devices — tenant-level OneDrive settings that stop sync altogether on unmanaged machines; relevant because a hydrated file is a local copy of company data.

There is deliberately no policy to pin specific folders for every user. If the business wants a given library always local, it's a user action or a script (attrib +p on Windows), not a setting.

The compatibility problems

Backup and imaging tools. Anything that reads files to back them up hydrates them. Modern backup agents are cloud-files-aware and skip placeholders or back up metadata; older ones download everything. Check before deploying to laptops.

Antivirus and DLP scanners. Real-time scanning on access is fine; scheduled full scans can hydrate. Defender is cloud-files-aware; third-party products vary.

Line-of-business apps that assume local I/O. Apps that memory-map files, open with unusual flags, or time out on slow opens can fail on a placeholder. The fix is usually to pin the folder the app uses.

Search and indexing. Windows Search indexes placeholder metadata (name, properties) but not content that isn't local. Users searching for text inside online-only files get no hits — one of the more common "search is broken" tickets.

Offline work. A user who never pinned anything opens the laptop on a train and finds a folder of cloud icons. This is the number-one Files On-Demand complaint and it's a training problem: teach "Always keep on this device" for the folders that matter.

Large-scale hydration. A script, a build, or a migration tool pointed at a synced folder can pull gigabytes without warning. The OneDrive client will throttle; the network team will notice.

The mental model to teach

The cloud icon means "we know about it, it isn't here yet." The outlined tick means "it's here for now." The solid tick means "it stays." Everything else — the reparse points, the filter driver, Storage Sense — is plumbing to make those three states honest. Teach the icons, pin what's important, enable Storage Sense, and test the backup agent before rollout. That covers nearly every Files On-Demand ticket you'll ever see.