OneDrive Files On-Demand and Business Apps — The Assumptions Placeholders Break and How to Fix Them

“A business app cannot read the CSV I saved on the desktop.” “After we replaced the PC, the import that used to work stops with ‘file not found’.” Because Explorer shows the file, saving it again or restarting the app sometimes brings you no closer to the cause.

At that point, two things are worth checking separately: where the file is and whether its contents are on the local disk. OneDrive’s Known Folder Move (KFM) changes the location of the Desktop and similar folders, and Files On-Demand keeps the contents in the cloud until they are needed. Both cause problems when a business app assumes a traditional local file.¹²

This article, written for IT staff at small and medium-sized businesses and for Windows app developers, starts with a triage procedure for these support requests. It then explains how placeholders work and how to read their attributes, the pitfalls business apps run into, and what the development side and the IT side can each do.

1. The Bottom Line — Check the Location and the Contents Separately

A file being visible in Explorer guarantees neither that the app is looking at the right path nor that the contents can be read right away. Start by separating the following two questions.

Get paths moved by KFM from the known-folder APIs. For Files On-Demand, check the attributes first and open only the files whose contents you need. Files On-Demand is enabled by default in the current sync app, and Microsoft recommends leaving it enabled. A problem is no reason to disable it across the board from the outset.¹³⁴

The stopgap is to set the folders the business needs to “Always keep on this device” so that the contents are present locally. Correcting a wrong path, however, is a separate task. The permanent fix is for the app side to review where it stores data, how it reads, and how it watches, and for the IT side to maintain the required state with pins and policy.

In the diagram a solid line marks a relation that always holds and a dashed line marks a conditional one (the conditions are given per relation on the detail page). The full list of relations (16 in total, with evidence and certainty) and the definitions of the main concepts are collected on the knowledge map detail page (in Japanese). Data: JSON-LD / Turtle

2. Triage When Someone Reports “The File Cannot Be Read”

2.1. Check Six Items, Starting From the Path

Rather than opening every file in the target folder right away, investigate from the path and the metadata. This procedure keeps the existence check and the read separate.

Depending on which OneDrive is in use, personal or work, the OneDrive / OneDriveCommercial environment variables are also a clue. Do not judge by the display name “Desktop” alone; what matters is to compare against the path the app actually referenced.

If the path is not under OneDrive and the file is not a placeholder, stop suspecting only OneDrive and move on to checks such as shared folders and path length. “Pitfalls of Network Drives and UNC Paths” and “MAX_PATH and Windows Path/Filename Pitfalls” cover those other families of causes.

2.2. Separate the Stopgap From Confirming That Work Can Resume

If the file is online-only and its contents cannot be read, right-click the target folder and choose “Always keep on this device”. To switch it from a script, use something like attrib +p -u <folder> /s /d, which pins and clears the unpinned attribute at the same time.⁶⁷

What you want to confirm here is not that the operation was performed, but that the download of the required files has finished and they can be read. A pin is an attribute that expresses the intent to keep the file locally; it does not resolve a stopped OneDrive, a poor network, or a lack of free space. Check the sync app’s state and the actual contents of the target file, then rerun the import.³⁶

After recovery, go to the app-side measures in Chapter 6 if a fixed path or the data layout was the cause, and to the IT-side measures in Chapter 7 if the cause was local content retention or inconsistent device settings. That the pin made it work once is not the same as a design that will not fail again.

3. What Changed — How KFM and Placeholders Work

3.1. KFM Changes the Real Path of the Desktop and Similar Folders

KFM (Known Folder Move) is the feature that the OneDrive settings screen shows as “Backup”, “Back up important folders”, and the like. When it is enabled, the actual Desktop, Documents, and Pictures folders move under OneDrive. The paths below are examples. The actual folder names and the sync root differ by environment, so do not embed these strings in code as they are.¹

Some configurations propose the backup when the user signs in with a Microsoft account or a work account during the initial setup (OOBE) of a new PC, and it is enabled as the user proceeds. In an organization, the KFMSilentOptIn policy can move the folders for everyone at once with no user action. Do not assume it was only ever enabled by a user who did so deliberately.¹⁸

The awkward part is that Explorer looks almost the same. An app that uses SHGetKnownFolderPath or .NET’s Environment.GetFolderPath gets the post-move path. An app that has a fixed path such as C:\Users\%USERNAME%\Desktop embedded in a settings file or in code, on the other hand, keeps looking in the old location.

In other words, handling KFM is first of all a path-resolution problem. Once you know the correct post-move path, then check whether that file’s contents are on the local disk.

3.2. Files On-Demand Separates “Being Visible” From “Having Contents”

In an environment where Files On-Demand is enabled, synced files appear in Explorer while their contents are not downloaded until they are needed. Files created on another device or on the web also appear, as online-only placeholders.²⁴

The state can be told from the icon in Explorer.⁹

The important point is that “locally available”, the state of a file that has been opened once, is different from “Always keep on this device”, the state of a pinned file. The former can return to online-only through the user’s “Free up space” action or through Storage Sense. “It could be read last month” is no evidence that the contents are still present this time.²¹⁰

stateDiagram-v2
    accTitle: The three Files On-Demand states and their transitions
    accDescr: An online-only file becomes locally available when opened, but a Free up space action or Storage Sense returns it to online-only, and only a pinned file is exempt from automatic freeing
    s1: Online-only (cloud icon)
    s2: Locally available
    s3: Pinned (Always keep on this device)
    s1 --> s2: Open (hydration)
    s2 --> s1: Free up space
    s2 --> s1: Storage Sense
    s1 --> s3: Always keep on this device
    s2 --> s3: Always keep on this device
    s3 --> s2: Unpin

Figure 1: Unlike a pinned file, a file that has merely been downloaded once can be freed automatically.

3.3. On a Read, the Cloud Files API Fetches the Contents

Files On-Demand is implemented on top of the Cloud Files API, introduced in Windows 10 version 1709. On the file system side, a minifilter named cldflt.sys (service name CldFlt, the Windows Cloud Files Filter Driver) does the work, and OneDrive is one of the sync providers that use this API.¹¹⁶

A placeholder that does not yet have contents is a reparse point holding only metadata such as the file name, size, and timestamps. According to Microsoft, it uses about 1 KB to store the file system header. When an app tries to read the contents, the minifilter asks the sync provider to transfer the data, and the read proceeds once the required data has arrived. This fetch is called hydration, and freeing the local contents to return the file to a placeholder is called dehydration.¹¹

sequenceDiagram
    accTitle: Hydration when a placeholder is opened
    accDescr: When an app opens and reads a placeholder, the cldflt.sys minifilter detects the request, tells the sync provider to transfer the data, waits for the download to finish, and then lets the read proceed
    participant app as Business app
    participant flt as cldflt.sys minifilter
    participant sync as Sync provider
    app->>flt: Open and read request
    flt->>sync: Instruct data transfer
    sync-->>flt: Download complete
    flt-->>app: Read proceeds

Figure 2: In the middle of what looks like a local file read, a download by the sync provider takes place.

For compatibility, the Cloud Files API hides the fact that the file is a reparse point from every process other than the sync engine and processes under %systemroot%. To an ordinary app it therefore looks like an ordinary file that is merely a little slow to open. Do not rely on code that treats reparse points specially to make the decision; check the attributes described in the next chapter instead.¹¹ The mechanism of reparse points themselves is explained in “NTFS Internals”.

In Explorer’s Properties, “Size” shows the original file size, while “Size on disk” is close to 0. That a file has a name and reports a size is a different matter from its contents being on the local disk.

4. Checking the State From File Attributes

4.1. Read the State of the Contents and the Retention Intent Separately

A placeholder’s state is exposed as ordinary file attributes. The main ones are as follows.³

OFFLINE and RECALL_ON_DATA_ACCESS are clues to whether the data is immediately available. PINNED / UNPINNED, on the other hand, express the intent to keep the file locally. Do not conclude from P or U alone that the download has finished. Also, RECALL_ON_OPEN is an attribute that appears in directory enumeration results and is not returned in the same way by every attribute-query API.³

4.2. When Checking and Changing With attrib, Mind the Order of Switching

attrib <path> shows the attributes. O stands for offline, P for pinned, and U for unpinned. Microsoft maps the OneDrive states to the setting commands as follows.⁷⁶

Running only attrib -p on an online-only (U) file leaves U in place and does not fetch the contents. Even when the goal is “locally available”, the order must be first +p to make the file “always available” and download the contents, then -p. A script that switches an existing state should also clear the opposite attribute, as in attrib +p -u.⁶

4.3. Bulk-Check the State of CSV Files With PowerShell

Looking only at file attributes lets you investigate without hydrating the contents. The following example gets the Documents path from the known-folder API and checks the attributes of CSV files.

function Test-CloudPlaceholder {
    param([Parameter(Mandatory)][string]$Path)

    $value = [int](Get-Item -LiteralPath $Path -Force).Attributes

    [pscustomobject]@{
        Path               = $Path
        Offline            = ($value -band 0x00001000) -ne 0  # FILE_ATTRIBUTE_OFFLINE
        RecallOnDataAccess = ($value -band 0x00400000) -ne 0  # Not all of the contents are local
        Pinned             = ($value -band 0x00080000) -ne 0  # Always keep on this device
        Unpinned           = ($value -band 0x00100000) -ne 0  # Online-only
    }
}

# Bulk-check the CSV files under the Documents folder (the contents are not downloaded).
# Resolve the path with the known-folder API. Hardcoding the display name "Documents"
# yields a nonexistent path in environments where the real folder name is localized
# or depending on the KFM configuration
Get-ChildItem ([Environment]::GetFolderPath('MyDocuments')) -Recurse -Filter *.csv |
    ForEach-Object { Test-CloudPlaceholder $_.FullName } |
    Where-Object RecallOnDataAccess |
    Format-Table -AutoSize

The cast to [int] is needed because .NET’s FileAttributes enumeration does not define names such as RECALL_ON_DATA_ACCESS. Convert to a number and test with bitwise operations. Both points matter: avoiding a hardcoded display name such as “Documents”, and looking at the attributes without reading the contents.

5. Six Problems That Surface in Business Apps

A placeholder is not a broken file. It does, however, sit badly with assumptions such as “a file that exists can be read right away” or “a watch event on a local folder comes from a user action”.

5.1. The Existence Check Passes, but the Read Fails

Even for an online-only file, an existence check equivalent to File.Exists() and queries for attributes and size can succeed. Hydration becomes necessary the moment the contents are read, so a stopped, signed-out, or paused OneDrive, or a poor network, shows up as a read failure. With a large file, waiting for the download can also hit the app’s timeout.

Cloud-file errors include 0x8007016A (“The cloud file provider is not running”), which corresponds to ERROR_CLOUD_FILE_PROVIDER_NOT_RUNNING. Do not lump these together as “file missing”; record the original error code and the target path.⁵

5.2. Batch Processing Triggers a Download of Everything

Point a batch that reads every file in a folder, a hash computation, a full-text search, or a homegrown backup at a folder under OneDrive, and every file whose contents are read is hydrated one after another. For a folder of several GB, not only the processing time but also network traffic and local disk consumption grow. On a PC with little storage, this leads to a separate failure from a lack of free space.

When an app fetches files the user did not explicitly open, Windows may show a notification and offer the user the option to block it. Once blocked, that app’s subsequent downloads fail. The block is lifted under “Automatic file downloads” in Settings. When “it fails only on a particular PC”, check this state too.¹¹

5.3. Code That Does Not Expect the Extra Attributes Misjudges

An exact-match test such as attributes == FileAttributes.Archive excludes any file that has acquired other attributes as “unexpected”. There are also cases where a backup or sync tool interprets OFFLINE as “already migrated to tape” and skips the file, or, conversely, fetches files it did not need. A read-only check or a change to the archive bit must also not destroy the combination of the other attributes.

Microsoft’s guidance for minifilter developers includes a caution against issuing careless reads or writes to a file that carries RECALL_ON_DATA_ACCESS. The constraints for kernel drivers and a user-mode implementation are not identical, but the point that touching the contents incurs a fetch cost is one that business apps need to keep in mind as well.¹²

5.4. FileSystemWatcher Also Picks Up Sync Activity

When you watch a folder under OneDrive with FileSystemWatcher, events can fire not only for user actions but also when changes from other devices are synced and when hydration or dehydration updates attributes or size.

On top of that, writing the import result back to the same folder creates a loop: write, upload, attribute update, and another event.

flowchart TB
    accTitle: The change-notification loop from watching and writing back
    accDescr: When a watching app that received a change event writes the import result back to the same folder, the sync app's upload and attribute update raise another event, producing a loop that becomes a storm of change notifications
    ev["Change event"] --> proc["The watching app imports"]
    proc --> write["Write back to the same folder"]
    write --> up["The sync app uploads"]
    up --> attr["Attributes or size are updated"]
    attr --> ev
    sync["Sync of changes from other devices"] -.-> ev

Figure 3: Writing the import result back to the watched folder can drag the sync app’s activity into a repeating cycle of notifications.

Why event thinning and a check of the actual contents are needed is covered in “A Practical Guide to FileSystemWatcher”. Under OneDrive, a design that does not read a notification as “one importable file has arrived” becomes all the more important.

5.5. Exclusive Locks and Edits on Several PCs Collide With Sync

While a business app holds a file open with an exclusive lock, the sync app can neither upload nor update that file. A design that keeps an Access .accdb, a data file in a proprietary format, or a log open for a long time makes sync errors the normal state once the file is placed under OneDrive.

When the same file is edited on several PCs, conflict copies such as a file with the PC name appended or a “copy of” file may be generated so that both versions are kept. An import that assumes “one folder, one file” misbehaves on these duplicates. For lock design, see also “Mutual Exclusion Fundamentals for File-Based Integration”.

5.6. Scans and the Search Indexer Also Fetch the Contents

Business apps are not the only things that read contents. A full scan by antivirus software or the search indexer also triggers hydration if it accesses the contents of a placeholder.

The Azure File Sync planning guide explains that Microsoft Defender and similar products skip files with the RECALL_ON_DATA_ACCESS attribute during on-demand scans. That, however, is an accommodation on the product side, and not every security product can be expected to take the same care. When “the network and disk are pegged every time the nightly scan runs” or “every file that was set to online-only has been materialized by the next morning”, examine the scanner’s behavior as well.¹³

6. Measures on the App Development Side — Do Not Open Carelessly, and Keep Data Elsewhere

6.1. Check Attributes During Enumeration and Read Only the Files Whose Contents You Need

The basic policy is to treat a placeholder as “a file with a fetch cost”. Give non-essential processing such as log collection, hash computation, and preview generation the option to skip such files.

The following example checks the attributes before importing a CSV.

// Define values that FileAttributes in .NET does not define, as numbers
const FileAttributes RecallOnDataAccess = (FileAttributes)0x00400000;
const FileAttributes RecallOnOpen       = (FileAttributes)0x00040000;

static bool IsCloudPlaceholder(FileAttributes attributes) =>
    (attributes & (RecallOnDataAccess | RecallOnOpen | FileAttributes.Offline)) != 0;

foreach (var file in new DirectoryInfo(watchFolder).EnumerateFiles("*.csv"))
{
    if (IsCloudPlaceholder(file.Attributes))
    {
        log.Warn($"{file.Name} is online-only, skipping it this run");
        continue;
    }
    Import(file.FullName);
}

This example takes the policy of not processing files that may be online-only in this run. Do not let files the business must import be treated as processed with nothing but a warning in the log. Decide together on an operational practice that secures the contents in advance and on how to handle read failures.

6.2. Do Not Treat FILE_FLAG_OPEN_NO_RECALL as a Guarantee of No Network Traffic

CreateFile’s FILE_FLAG_OPEN_NO_RECALL is a flag expressing the intent that the requested data stay on the remote side and not be moved back to local storage. It is not a flag that prohibits the data transfer needed to read the contents.¹⁴

In an investigation where you want to avoid bandwidth use and waiting, make do with metadata such as attributes, size, and timestamps. Choose methods that do not request read access: use the information from the enumeration results, or, when needed, open with an access mask of 0 to get the attributes.¹⁴

6.3. Put Data Placement and Failure Guidance in the Specification

In a KFM environment, “Documents” can also be under OneDrive. Place the app’s settings, database, and working files in a location that fits their purpose, such as %ProgramData% or %LocalAppData%, and do not casually pick the Desktop or Documents as the default save or import location. The concrete decisions are summarized in “How to Choose Where a Windows App Stores Local Data”.

Even when users can choose the save location, decide in advance how the app behaves when they choose a location under OneDrive. Include in the specification decisions such as warning based on the sync root revealed by the OneDrive / OneDriveCommercial environment variables, and refusing to place lock files or a database there.

When a read fails, display and record, in addition to the target path and the error code, the fact that the path is under OneDrive if that can be determined. Merely being able to say “check the state of OneDrive” when 0x8007016A or similar is detected makes it easier for the people on site and the help desk to investigate with the same checklist.

7. Measures on the IT Side — Maintain the State With Pins and Policy

7.1. Pin Only the Folders That Need It

Before disabling Files On-Demand across the board, set the folders that business apps read to “Always keep on this device”. When you use attrib +p -u <folder> /s /d during device provisioning, confirm that the download has finished before handing the device over for business use.⁶⁴

Merely “having opened the file once” does not prevent later automatic freeing. The key is to pin the required locations at folder level and to include that state in the support procedures.

7.2. Configure KFM and Files On-Demand Deliberately

To avoid “it was enabled before anyone noticed”, control the settings with Group Policy or Intune. Because there are also policies that prohibit reverting, check not only the device’s screen but also the settings the organization applies.⁸¹

DehydrateSyncedTeamSites is a policy that works in the direction of reducing the local contents of synced team sites. When required files return to the cloud icon, check these organizational settings as well as the user’s own “Free up space” action.⁸

7.3. Check Storage Sense and the Cost of Full Sync

Storage Sense has a feature that returns cloud files that have not been opened for a set number of days to online-only. The number of days is configured with ConfigStorageSenseCloudContentDehydrationThreshold, and the policy’s default of 0 means no automatic reverting. Users may, however, have enabled it on the settings screen, or the organization may have configured it for devices with little storage.¹⁰

What is affected are “locally available” files that have not been explicitly pinned. Pinned files are exempt from automatic freeing, so when “it could be opened until last week but has gone back to the cloud icon”, verify whether the P attribute was really set.⁴

Disabling FilesOnDemandEnabled returns to traditional full-download sync, but disk consumption and the bandwidth load of the initial sync increase. Microsoft recommends leaving it enabled. Treat disabling it as a limited measure taken after checking the data volume and disk capacity of the users concerned.⁸⁴

Build the sequence from Chapter 2, path, attributes, OneDrive running, network, free space, record, into the help-desk template. That way, even when staff change, the cause is investigated in the same order instead of settings being flipped at random.

8. Summary

File failures in a OneDrive environment become manageable once you separate “has the location changed?” from “do the contents need to be fetched?”. Handle KFM by resolving paths through the known-folder APIs, and handle Files On-Demand with a design that checks attributes and then reads only the contents it needs.

On top of that, review how processes such as writing back to a watched folder, long exclusive locks, and full scans overlap with sync. Keep the app’s internal data out of OneDrive, and keep the contents of the files the business needs in place with pins and policy. This division of roles is the basis for not stopping at a stopgap.

The next time someone reports “the file is there but cannot be read”, ask first:

Is the app looking at the current, correct location? And are that file’s contents really on the local disk?

Related Articles

• The Depths of Windows I/O (Part 5) — NTFS Internals: Understanding the File System Through the MFT
• A Practical Guide to FileSystemWatcher - Handling Missed and Duplicate Events
• Pitfalls of Network Drives and UNC Paths — Working With File Servers (Shared Folders) From a Business Application
• Mutual Exclusion Fundamentals for File-Based Integration - Best Practices for File Locks and Atomic Claims
• How to Choose Where a Windows App Stores Local Data — A Decision Table for SQLite / JSON / Registry / Access
• MAX_PATH and Windows Path/Filename Pitfalls — the 260-Character Limit, Reserved Names, Trailing Dots, and Case Sensitivity

Related Consulting Areas

KomuraSoft LLC handles investigations of business app failures involving OneDrive and cloud storage, such as “the import that used to work stopped working after a PC replacement” or “the file cannot be read only on a particular PC”, the design and remediation of file processing and watching that takes placeholders into account, and reviews of save-location design for KFM and Files On-Demand environments. Feel free to contact us, even if only to help triage the symptoms.

• Windows App Development
• Bug Investigation & Root-Cause Analysis
• Technical Consulting & Design Review
• Contact

References

Related Articles

Recent articles sharing the same tags. Deepen your understanding with closely related topics.

Related Topics

These topic pages place the article in a broader service and decision context.

Where This Topic Connects

This article connects naturally to the following service pages.

Frequently Asked Questions

Common questions about the topic of this article.

A business app says "file not found" and cannot read a CSV I put on the desktop. Why?

In many cases the Desktop folder itself has been moved under C:\Users\<username>\OneDrive\Desktop by OneDrive's Known Folder Move (KFM), or the file has become an online-only placeholder. An app that assumes a fixed path such as C:\Users\<username>\Desktop cannot find the file after the move. Even when the path is correct, an online-only file may fail to open while OneDrive is stopped or the network is unhealthy. First check whether the target path is under OneDrive, then use the attrib command to see whether U (online-only) is set. As a stopgap, "Always keep on this device" on the right-click menu secures the contents locally.

Can a program tell whether a file is online-only?

Yes. An online-only placeholder carries attributes such as FILE_ATTRIBUTE_OFFLINE and FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS (0x00400000), so inspecting the file attributes determines the state without downloading the contents. Getting attributes or enumerating a folder alone does not cause hydration (a download). In .NET some values are not defined on FileAttributes, so cast to an integer and test with bitwise operations. If you truly need to open a file without reading its contents, means such as CreateFile's FILE_FLAG_OPEN_NO_RECALL are also available.

Does disabling Files On-Demand solve the problem?

Treat disabling it as a last resort. Disabling it downloads every synced file locally, which increases disk usage and the network load of the initial sync, and Microsoft recommends leaving it enabled. In practice it is more flexible to set only the folders the business app reads to "Always keep on this device" (pin them). More fundamentally, the reliable fix is to redesign so that the app's data folder and import folder are not under OneDrive's management.

I set "Always keep on this device", but some files eventually go back to the cloud icon. Why?

First confirm with the attrib command that the file really is pinned (the P attribute). Pinned files are exempt from Storage Sense's automatic conversion to online-only, but a file that is merely "locally available" because it was opened, without being pinned, can be returned to online-only after a period depending on Storage Sense settings and policy. The user's own "Free up space" action and the policy that converts team sites to online-only (DehydrateSyncedTeamSites) also bring the cloud icon back. Pin the folders the business truly needs locally at folder level and operate that way.

Author Profile

Profile page for the article author.

Go Komura

Representative of KomuraSoft LLC

Focused on Windows software development, technical consulting, and investigations into failures that are difficult to reproduce.