Your Cloud Drive Dehydrated Your Notes — and Your AI Read the Stub

Reference: Understand Azure File Sync cloud tiering — Microsoft Learn · vendor documentation, page revised 2026-04-09

A note in cloud-only mode keeps its name, its path, and its full reported size while its content sits on a server. Every tool that opens it gets a file-shaped nothing: the read succeeds, the bytes are absent. One command separates the two cases — stat — and the field to read is Blocks.

This is not corruption and it is not a bug. Every behavior in this post is documented by the vendor that shipped it, deliberately, to save disk space. Microsoft's own page on cloud tiering states the mechanism in one line: "For tiered files, the size on disk is zero because the file content itself isn't being stored locally." ¹ Apple ships an enum member for the same state.

The design is sound and the trade is a good one. What is underappreciated is what it does to a retrieval pipeline pointed at a folder of notes.

A retrieval pipeline does not ask whether a file is present. It walks a directory, opens what it finds, reads what comes back, and embeds it. A placeholder passes every check that pipeline performs — the path resolves, the permission bits allow the read, the encoding is valid UTF-8, the extension is .md. The file is present, readable, permitted, correctly encoded, and hollow.

What does a dehydrated note look like from the outside?

It looks correct. The path resolves, the permissions are fine, the name is unchanged, and stat reports a size in the tens of kilobytes. One field disagrees with all of that. Blocks: 0 means the file was given no storage on this disk, because its content is not on this disk.

A bug report filed against an agent CLI in May 2026 carries the receipt in the wild. The reporter pasted the output of stat on a Markdown file inside a OneDrive folder:

$ stat 10-runtime-design.md
  Size: 137377   Blocks: 0       IO Block: 262144 regular file

Then the reporter wrote down the rule they had derived from it: "Blocks: 0 (or any value much smaller than Size / 4096) is the giveaway." ²

That rule was worked out in the field, not read off a manual, which is roughly the state of this knowledge in 2026.

Notice what the file survives. A test -s check passes, because st_size is non-zero. A directory listing looks right. A file count matches the count you expected. wc -c returns 137,377. The checks a careful script reaches for first all agree that the note is there.

Three numbers sit on that stat line, and only two of them describe the file's content. The third is a red herring that this post disarms in a moment.

Why do the two numbers disagree?

Because they measure different things. POSIX defines st_size as, for a regular file, "the file size in bytes", and st_blocks as the "Number of blocks allocated for this object." ³ One is how long the file is. The other is how much storage it was actually given. Nothing in the standard requires them to agree.

You can reproduce the divergence locally in two commands. This is a sparse file, not a cloud placeholder — the distinction matters and is spelled out below — but the metadata signal it produces is identical, which is what makes it a usable rehearsal for the real thing:

$ head -c 137377 /dev/urandom > real.md
$ truncate -s 137377 stub.md

$ stat real.md
  File: real.md
  Size: 137377    	Blocks: 272        IO Block: 4096   regular file

$ stat stub.md
  File: stub.md
  Size: 137377    	Blocks: 0          IO Block: 4096   regular file

Both files are 137,377 bytes long. One of them was given 272 blocks and the other was given none. ⁴

Be precise about what a block is, because the folklore here is wrong. POSIX explicitly declines to fix the unit: "The unit for the st_blocks member of the stat structure is not defined within POSIX.1-2024. In some implementations it is 512 bytes. It may differ on a file system basis." ³

On Linux and BSD it is 512 bytes in practice — stat -c %B returns 512 on the machine that produced the output above ⁴ — but the standard makes no such promise, and a diagnostic that treats 512 as guaranteed is quoting folklore. The Linux manual page attaches its own warning: "Use of the st_blocks and st_blksize fields may be less portable. (They were introduced in BSD. The interpretation differs between systems, and possibly on a single system when NFS mounts are involved.)" ⁵

Which brings us to the third number. IO Block is st_blksize, the filesystem's preferred size for an I/O operation. It is not a count of anything the file owns, and the standard is blunt about its relationship to the other field: "There is no correlation between values of the st_blocks and st_blksize, and the f_bsize (from <sys/statvfs.h>) structure members." ³

Remember that sentence for two sections' time. It is about to matter.

What does Windows call a file that isn't there?

A placeholder, or a tiered file. Microsoft's cloud-sync-engine documentation defines three states — placeholder, full, and pinned full — and the Win32 file-attribute table gives applications two flags for detecting them. ^{6 7} The state is a supported, queryable property of the file, not an accident of syncing.

The sync-engine page describes the storage shape directly: "Sync engines can create placeholder files that consume only 1 KB of storage for the filesystem header, and that automatically hydrate into full files under normal use conditions." ⁶ A kilobyte of header standing in for a hundred kilobytes of note.

The three states are named and defined on that same page: ⁶

• Placeholder file — "An empty representation of the file and only available if the sync service is available."
• Full file — "The file has been hydrated implicitly and could be dehydrated by the system if space is needed."
• Pinned full file — "The file has been hydrated explicitly by the user through File Explorer and is guaranteed to be available offline."

Read the middle one again. A file that is fully local today is not promised to be fully local tomorrow; the system may reclaim it when space is short. Only the third state carries a guarantee.

On the detection side, Microsoft is explicit that third-party applications are meant to be able to tell: "A tiered file has both the offline attribute and the FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS attribute set in NTFS so that third-party applications can securely identify tiered files." ¹

The attribute table defines what that flag means — "When this attribute is set, it means that the file or directory is not fully present locally" — and defines a sibling flag, FILE_ATTRIBUTE_RECALL_ON_OPEN, for the case where "the file or directory has no physical representation on the local system; the item is virtual." ⁷

Now the red herring. FILE_ATTRIBUTE_RECALL_ON_OPEN has the decimal value 262144, which is the same number that appeared as IO Block: 262144 in the field receipt above. The two are unrelated.

One is a bit position in an attribute word (0x00040000). The other is a filesystem's preferred I/O size on a Linux mount, and POSIX has already told us there is no correlation between it and the block count. ³ The coincidence is worth naming precisely because it is the kind of thing that gets confidently repeated once someone notices it.

The contrast case is on the same Microsoft page as the headline fact: for an ordinary file on a file server, "the size on disk is about equal to the logical size of the file". ¹ Tiering breaks that equality on purpose. The logical size stays — it is what the file will weigh once it comes back — and the size on disk goes to zero.

What does macOS call it?

notDownloaded. Foundation ships an enum, URLUbiquitousItemDownloadingStatus, whose one-line summary is "Values that describe the iCloud storage state of a file." ⁸ The member that names our case is documented as: "This item has not been downloaded yet. Use startDownloadingUbiquitousItem(at:) to download it." ⁸

The URL resource key that exposes the status says what it is for in a single sentence: "The value indicates whether a local copy exists and whether that copy is the most current version of the item." ⁹

Two questions, one property — is it here, and is it current.

That the API exists at all is the point. Apple did not add a status enum for a state that never occurs; the state is normal, and any tool that cares whether a file's bytes are local is expected to ask.

One deliberate omission. There is a widely circulated command-line recipe for forcing an iCloud download, along with confident claims about which macOS versions still ship it. None of that is documented on developer.apple.com, so this post prints neither the command nor any version claim in either direction. The documented path is the API path, and it is the one in the fix ladder below.

Where does the stub enter your AI pipeline?

At the read, and it never announces itself. The indexer opens the file, the operating system decides whether to fetch the content or hand back what it has, and the pipeline downstream sees one thing in both cases: a successful read on a file with a plausible name. The branch happens below the tool, in the filesystem.

flowchart TD
  A[Tool opens<br/>a note] --> B[Name and size<br/>look normal]
  B --> C{Content stored<br/>on this device?}
  C -->|Yes| D[Full text<br/>is read]
  C -->|Placeholder| E{Sync service<br/>reachable?}
  E -->|Yes| F[File hydrates<br/>over the network]
  F --> D
  E -->|No| G[No content<br/>to hand back]
  D --> H[Note enters<br/>the index]
  G --> H

Figure: The read path for a note in a cloud-synced folder. A tool opens the file and sees a normal name and size. If the content is stored on the device, the full text is read. If the file is a placeholder, the outcome depends on whether the sync service is reachable: when it is, the file hydrates over the network and the read succeeds; when it is not, there is no content to hand back. Both branches end in the same place — the note enters the index — which is why the failure is silent.

The two paths converge on the same downstream step, and nothing in that step distinguishes them.

A vector store has no column for "this chunk came from a file with no bytes."

Won't the file just download when something reads it?

Usually, on Windows, yes. Microsoft states it as a compatibility guarantee: "Whether you use file system APIs, the Command Prompt, or a desktop or a UWP app to access a placeholder file, the file will hydrate without additional code changes and that app can use the file normally." ⁶ Transparent hydration is the feature working as designed.

Three things follow from that guarantee, and none of them are reassuring for a batch job.

First, the guarantee is conditional on reachability. A placeholder is "only available if the sync service is available" ⁶ — so an indexing run on a plane, on a throttled connection, or against a signed-out account is exactly the run where the reads come back empty.

Second, hydration is not permanent. A hydrated file "could be dehydrated by the system if space is needed" ⁶. A vault you verified last month is not a vault you have verified.

Third, a successful hydration is itself a decision you did not make. Every placeholder your indexer touches gets pulled down over the network, because a batch walk looks identical to a user double-clicking.

The failure mode worth taking seriously is not the read. It is the write-back.

The reporter in that bug report described what happens when a tool reads a truncated file and then saves it: "it silently overwrites the user's full cloud copy with the truncated stub plus whatever edits Cowork made. The user loses data silently. No error, no warning, no diff prompt." ²

Read-modify-write on a file you did not fully read is a data-loss pattern, and it is why the ladder below says hydrate before you point anything with write access at the vault.

How do I check a single file?

Run stat and read two fields. A non-zero Size next to Blocks: 0 is the signal. Then confirm with du, which by default reports what the file occupies on the device, against du --apparent-size, which reports the logical length. When those two numbers diverge, the gap is the content you do not have.

$ stat stub.md | head -2
  File: stub.md
  Size: 137377    	Blocks: 0          IO Block: 4096   regular file

The du pair makes the same point without needing you to know what a block is:

$ du -h real.md stub.md
136K	real.md
0	stub.md

$ du -h --apparent-size real.md stub.md
135K	real.md
135K	stub.md

GNU's own manual page defines the flag and, usefully, names our exact situation in the definition: --apparent-size prints "apparent sizes rather than device usage; although the apparent size is usually smaller, it may be larger due to holes in ('sparse') files, internal fragmentation, indirect blocks, etc." ¹⁰

So: du answers "what is this costing me?" and du --apparent-size answers "how long does this file claim to be?" A real file gives similar answers to both. A hollow one gives 0 and 135K.

What the local reproduction is and is not. The real.md / stub.md pair above is a sparse file made with truncate, on ext4, with GNU coreutils 9.4 on Linux 6.8.0-124 ⁴. It reproduces the metadata divergence exactly, which is the whole diagnostic.

It does not reproduce cloud read semantics. Reading the sparse stub returns 137,377 bytes and every one of them is a NUL, whereas a real placeholder either hydrates over the network or is unavailable. ⁶ Treat it as a rehearsal for the signal, never as a demonstration of what a sync filter does on read.

$ wc -c < stub.md
137377
$ tr -d '\0' < stub.md | wc -c
0

A file-shaped nothing, and a tokenizer will happily consume it.

How do I sweep an entire vault?

Ask the filesystem for two fields per file and let awk find the disagreement. On GNU systems, find -printf prints the byte size (%s) and the allocated 512-byte blocks (%b) in one pass, and any file with a non-zero size and zero blocks is a suspect:

$ find ~/notes -type f -size +0c -printf '%s %b %p\n' \
  | awk '$2==0 {print "SUSPECT (0 blocks, nonzero size):", $3, "size="$1}'
SUSPECT (0 blocks, nonzero size): ./stub.md size=137377

That is the measured output from the reproduction above, on this Linux machine. ⁴

find -printf is a GNU extension and is not present on macOS, which is where iCloud Drive lives. The BSD route asks stat for the same two fields instead, using its format flags, and lets awk apply the same rule:

# macOS / BSD — no -printf; ask stat for size (%z) and allocated blocks (%b)
find ~/notes -type f -exec stat -f '%z %b %N' {} + \
  | awk '$1 > 0 && $2 == 0 {print "SUSPECT:", $3, "size=" $1}'

Two caveats on the BSD variant, stated plainly. It was not run on the machine that produced the receipts in this post, which is Linux; and the block-unit warning from the Linux manual page applies with extra force across platforms, since interpretation of these fields "differs between systems". ⁵ Verify the output on your own Mac against a file you know is downloaded before you trust the sweep on a file you don't.

On macOS there is also a route that does not depend on block accounting at all, and it is the one Apple documents: query ubiquitousItemDownloadingStatusKey on the URL, which reports "whether a local copy exists and whether that copy is the most current version of the item." ⁹ Where you can call Foundation, that answer is authoritative and the block heuristic is not.

What do I do with the files the sweep finds?

Hydrate them, then pin what must stay. The sweep is a detector, not a repair — it names the hollow notes and changes nothing. On Windows the durable answer is pinning; on macOS it is an explicit download request through Foundation. Everywhere, the ordering rule is the same: hydrate before you index, index before you let anything write.

That order is the whole ladder. The rest is per-platform detail.

Windows. Pinning moves a file into the third state, and Microsoft's definition is the guarantee you are buying: a pinned full file "has been hydrated explicitly by the user through File Explorer and is guaranteed to be available offline." ⁶ The unpinned alternative carries the opposite property — the system may dehydrate it "if space is needed". ⁶ Pinning is the difference between a policy and a hope.

macOS. Probe first, then download. The status key tells you whether a local copy exists ⁹; the enum member for a file without one names its own fix: "Use startDownloadingUbiquitousItem(at:) to download it." ⁸ The call is asynchronous, so a pipeline that wants the bytes must ask for them and then wait for the status to change before reading.

Any platform. Re-run the sweep after hydrating rather than assuming it worked, and re-run it before each indexing job rather than once. The middle state in Microsoft's list is the reason: hydration is reversible by the system, on the system's schedule, without asking you. ⁶

And the order matters most for write-capable tools. A stub read followed by a save is how a full cloud copy gets replaced by a truncated one, with "no error, no warning, no diff prompt." ² Point read-only tooling at an unverified vault if you must. Never point a writer at one.

What does this check not tell you?

That the note is correct. Blocks: 0 catches one specific failure — the file has a length and no content on this device — and it is silent about everything else. It also inherits the portability limits of the fields it reads, which are real and documented, and it does not survive being turned into a universal rule.

Four limits, in order of how likely they are to bite:

1. It is a heuristic on a non-standard field. POSIX does not define the unit of st_blocks ³, and the Linux manual page warns that interpretation "differs between systems, and possibly on a single system when NFS mounts are involved." ⁵ The rule holds on ext4 and on the platforms most vaults live on; it is not a specification.
2. Compression and deduplication also break the equality. Any storage layer that stores fewer blocks than the logical length produces a similar shape. The signal says "these two numbers disagree", not "the cloud took your file".
3. A hydrated file can pass today and fail next week. ⁶ A one-time audit is a snapshot of a mutable property.
4. It is not the same audit as a file-count audit. A count-based coverage check compares how many files exist against how many the tool read — and every dehydrated note is counted in both, because it exists, resolves, and reads. The counts match perfectly while the content is missing.

That last one is why this failure survives the audits people already run.

The sixth blind spot

We have written before about five documented defaults that make a local AI silently skip files: symbolic links, dot-files and ignore rules, text encoding, binary attachments, and file permissions. Dehydration is none of them, which is exactly what makes it worth a separate name. In those five, the file is skipped. Here, the file is read.

That difference is not a technicality. It is why the existing check misses it.

The earlier piece, Ask Your AI What It Can't Read, builds its smoke test on a count mismatch — how many files are on disk versus how many the tool ingested. A dehydrated note defeats that test by design: it is on disk, it is counted, it is opened, and it is read successfully. The gap the test looks for never appears. The sixth blind spot is the one where every number agrees and the content is still gone.

Two neighbours are worth knowing about. Don't Let the AI Be Your Only Way Into Your Notes argues reachability as an architecture question rather than a diagnostic one; this post is the narrow case where the path resolves and the content does not follow. And A .gitignore for Your Notes is the mirror image: junk the operating system creates in your vault, versus content the operating system evicted from it. Different direction, same lesson about defaults you did not choose.

None of this is an argument against cloud sync, which solves a real problem and states its trade-offs in public. It is an argument for knowing which of your notes are actually on the machine you are about to point a model at.

Local-first means the file is yours; whether it is present is a different question, and this diagnostic is how you answer it. Both answers should be yes before an index run, and only one of them is a matter of ownership.

Frequently Asked Questions

Why does my AI say my notes are empty after iCloud sync?

Most likely the files were never downloaded to that Mac. Their iCloud state is notDownloaded, which Apple documents as: "This item has not been downloaded yet. Use startDownloadingUbiquitousItem(at:) to download it." ⁸ The path resolves and the read succeeds, so the pipeline reports a file it processed and no content it found.

How do I check whether a note file is a placeholder?

Run stat <file> and read the Blocks: field. Zero blocks alongside a non-zero Size is the signal. ^{2 4} Cross-check with du <file> against du --apparent-size <file>: the first reports device usage, the second reports the logical length. ¹⁰ The gap between them is content you do not have locally.

Is st_blocks always in 512-byte units?

No. POSIX declines to define the unit: "In some implementations it is 512 bytes. It may differ on a file system basis." ³ It is 512 on Linux in practice — stat -c %B returns 512 on the test machine ⁴ — and the Linux manual page warns these fields "may be less portable" and that interpretation "differs between systems". ⁵

Does IO Block: 262144 mean the file has FILE_ATTRIBUTE_RECALL_ON_OPEN set?

No. The two are the same number and completely unrelated. IO Block is st_blksize, a filesystem's preferred I/O size; 262144 is also the decimal value of a Windows attribute bit (0x00040000). ⁷ POSIX states there is "no correlation" between st_blocks, st_blksize and f_bsize. ³

Is OneDrive Files On-Demand breaking my local AI a documented behavior?

Yes, on every side. A tiered file carries the offline and FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS attributes so applications "can securely identify" it ¹; that attribute means the file "is not fully present locally" ⁷; and a placeholder is "only available if the sync service is available." ⁶ Nothing here is undocumented.

Won't the file just download when something reads it?

On Windows, usually: "the file will hydrate without additional code changes and that app can use the file normally." ⁶ The failure case is precisely when the sync service is not reachable ⁶ — an offline or throttled indexing run. And hydration is reversible: a full file "could be dehydrated by the system if space is needed." ⁶

How do I guarantee a note stays local before indexing a vault?

On Windows, pin it: a pinned full file is "hydrated explicitly by the user through File Explorer and is guaranteed to be available offline." ⁶ On macOS, probe ubiquitousItemDownloadingStatusKey ⁹ and then call startDownloadingUbiquitousItem(at:) ⁸. Re-check after hydrating, and again before each run.

du or du --apparent-size — which one is the real size?

They answer different questions and you need both. Default du reports device usage; --apparent-size reports the logical length, which "may be larger due to holes in ('sparse') files". ¹⁰ Neither is more true than the other. The distance between them is the measurement.

A file is not a promise about its contents. It is a name, a length, and a claim about storage — and on a cloud drive, exactly one of those three can be a fiction.

MNMNOTE keeps notes as plain Markdown on your own device, working offline by default — mnmnote.com.

[
  {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "Your Cloud Drive Dehydrated Your Notes — and Your AI Read the Stub",
    "description": "A note in cloud-only mode keeps its name and reports its full logical size while its bytes sit on a server. One command tells you which is which: stat prints a non-zero Size next to Blocks: 0.",
    "articleSection": "Engineering",
    "datePublished": "2026-08-05",
    "dateModified": "2026-08-05",
    "author": {
      "@type": "Organization",
      "name": "MNMNOTE",
      "url": "https://mnmnote.com"
    },
    "publisher": {
      "@type": "Organization",
      "name": "MNMNOTE",
      "url": "https://mnmnote.com"
    },
    "mainEntityOfPage": {
      "@type": "WebPage",
      "@id": "https://blog.mnmnote.com/posts/your-cloud-drive-dehydrated-your-notes"
    },
    "keywords": "cloud sync, placeholder files, cloud tiering, st_blocks, local AI, note vault, OneDrive Files On-Demand, iCloud Drive"
  },
  {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    "itemListElement": [
      {
        "@type": "ListItem",
        "position": 1,
        "name": "Blog",
        "item": "https://blog.mnmnote.com/"
      },
      {
        "@type": "ListItem",
        "position": 2,
        "name": "Engineering",
        "item": "https://blog.mnmnote.com/category/engineering"
      },
      {
        "@type": "ListItem",
        "position": 3,
        "name": "Your Cloud Drive Dehydrated Your Notes — and Your AI Read the Stub",
        "item": "https://blog.mnmnote.com/posts/your-cloud-drive-dehydrated-your-notes"
      }
    ]
  },
  {
    "@context": "https://schema.org",
    "@type": "FAQPage",
    "mainEntity": [
      {
        "@type": "Question",
        "name": "Why does my AI say my notes are empty after iCloud sync?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Most likely the files were never downloaded to that Mac. Their iCloud state is notDownloaded, which Apple documents as: This item has not been downloaded yet. Use startDownloadingUbiquitousItem(at:) to download it. The path resolves and the read succeeds, so the pipeline reports a file it processed and no content it found."
        }
      },
      {
        "@type": "Question",
        "name": "How do I check whether a note file is a placeholder?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Run stat on the file and read the Blocks field. Zero blocks alongside a non-zero Size is the signal. Cross-check with du against du --apparent-size: the first reports device usage, the second reports the logical length. The gap between them is content you do not have locally."
        }
      },
      {
        "@type": "Question",
        "name": "Is st_blocks always in 512-byte units?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "No. POSIX explicitly declines to define the unit: In some implementations it is 512 bytes. It may differ on a file system basis. It is 512 on Linux in practice, and the Linux manual page warns these fields may be less portable and that interpretation differs between systems."
        }
      },
      {
        "@type": "Question",
        "name": "Does IO Block 262144 mean the file has FILE_ATTRIBUTE_RECALL_ON_OPEN set?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "No. The two are the same number and completely unrelated. IO Block is st_blksize, a filesystem's preferred I/O size; 262144 is also the decimal value of a Windows attribute bit (0x00040000). POSIX states there is no correlation between st_blocks, st_blksize and f_bsize."
        }
      },
      {
        "@type": "Question",
        "name": "Is OneDrive Files On-Demand breaking my local AI a documented behavior?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "Yes, on every side. A tiered file carries the offline and FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS attributes so applications can securely identify it; that attribute means the file is not fully present locally; and a placeholder is only available if the sync service is available. Nothing here is undocumented."
        }
      },
      {
        "@type": "Question",
        "name": "Won't the file just download when something reads it?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "On Windows, usually: the file will hydrate without additional code changes and that app can use the file normally. The failure case is precisely when the sync service is not reachable, such as an offline or throttled indexing run. And hydration is reversible: a full file could be dehydrated by the system if space is needed."
        }
      },
      {
        "@type": "Question",
        "name": "How do I guarantee a note stays local before indexing a vault?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "On Windows, pin it: a pinned full file is hydrated explicitly by the user through File Explorer and is guaranteed to be available offline. On macOS, probe ubiquitousItemDownloadingStatusKey and then call startDownloadingUbiquitousItem(at:). Re-check after hydrating, and again before each indexing run."
        }
      },
      {
        "@type": "Question",
        "name": "du or du --apparent-size: which one is the real size?",
        "acceptedAnswer": {
          "@type": "Answer",
          "text": "They answer different questions and you need both. Default du reports device usage; --apparent-size reports the logical length, which may be larger due to holes in sparse files. Neither is more true than the other. The distance between them is the measurement."
        }
      }
    ]
  }
]