AI AI Tools Guidebook
Troubleshooting

Cursor IDE State Out of Sync with Disk

Editor shows old content after an AI edit, or save says "file modified externally" — watcher / AI write race.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

AI writes straight to disk. The editor’s file watcher normally picks that up and refreshes the view. But on large files, network filesystems (WSL / Docker volumes), AV intercepts, or auto-save firing into an Apply — editor and disk briefly disagree. You see the old code while a teammate / the AI’s reply already references new code; save errors with “file has been modified externally”; one split pane is new and the other is old.

The fix isn’t blindly Cmd+S — that would overwrite the AI edit with a stale buffer.

Common causes

1. File watcher missed the AI write

macOS FSEvents / Linux inotify / Windows ReadDirectoryChangesW drop events under load or on network mounts. Cursor’s internal watcher also throttles. AI writes; editor never gets a refresh notification.

How to judge: cat file.ts in a terminal shows the new content; editor shows the old. Watcher didn’t fire.

2. Dirty buffer + AI write to disk

The tab shows a dot (unsaved buffer) while AI is writing to disk. Cmd+S flushes the buffer = overwrites the AI edit. Cursor usually prompts, but sometimes the buffer silently wins.

How to judge: look for the dot before and after Apply. A dot during Apply is the danger sign.

3. Same file in two split panes

VS Code / Cursor allow the same file in two panes, each with its own view model. AI writes; pane A refreshes; pane B doesn’t (it wasn’t recently focused).

How to judge: two panes show the same file with different contents.

4. WSL / Docker volume / network share event delay

/mnt/c/... (WSL boundary), Docker macOS osxfs volumes, SMB/NFS mounts, Dropbox/iCloud directories — file events can lag 5-30s or never arrive.

How to judge: project path matches any of the above; same AI action doesn’t repro on a native path.

5. Auto-save races Apply

Cursor files.autoSave: afterDelay flushes the dirty buffer ~1s later. If Apply lands right then, the editor’s stale buffer overwrites the new content.

How to judge: files.autoSave isn’t “off”; the issue time matches the autosave delay window.

6. AV / file lock briefly holds the file

Windows Defender, corporate AV, Spotlight indexing, Time Machine backup scans occasionally lock files for 200-500ms — right in the watcher throttle window.

How to judge: intermittent, correlates with AV scan time.

Before you start

  • Confirm if this is one specific file / time / project, or universal.
  • Commit before reproducing so revert has a baseline.
  • Note Cursor version and filesystem (macOS APFS, WSL ext4, Docker volume, SMB).

Info to collect

  • Cursor version, OS, filesystem type.
  • Project path (WSL /mnt/, Docker volume, network share, iCloud sync?).
  • files.autoSave setting; whether the file is open in multiple panes.
  • View → Output → Log (Window) — look for “missed event” / “throttled” entries.

Shortest fix path

“Save current file first → prevent recurrence.”

Step 1: Preserve buffer, then reload

If the tab has a dirty dot, copy everything to a scratch file first:

# macOS: select all → Cmd+C → terminal
pbpaste > /tmp/scratch-backup.ts

Then Cmd+Shift+P → “Revert File” — editor drops buffer and re-reads disk. Now decide whether to merge any of the scratch back in.

Step 2: For repo-wide mismatch, reload the window

Cmd+Shift+P → “Developer: Reload Window.” Cursor reloads all files and rebuilds watchers. Faster than quitting Cursor.

Step 3: Disable auto-save, at least during AI sessions

Settings → search files.autoSave → set to off or onFocusChange. Save manually after AI Apply so buffer can’t race write.

// settings.json
{
  "files.autoSave": "off",
  "files.hotExit": "onExit"
}

Step 4: Don’t split-pane the same file

Close the second pane, or use mirror split (not independent views). Cmd+Shift+P → “View: Close Other Editor Group.”

Step 5: Move project off /mnt/c to native WSL

In WSL2, /mnt/c/Users/you/repo crosses filesystem boundaries; watchers crawl. git clone to ~/repo (native ext4) is dramatically faster and more reliable.

Docker on macOS: switch the volume to cached or delegated, or keep the whole project inside the container.

Step 6: AV allowlists

Windows Defender / corporate AV → add project root + Cursor install directory to exclusions. macOS Spotlight:

sudo mdutil -i off ~/path/to/repo

Or System Settings → Spotlight → Privacy → add.

How to verify the fix

  • Restart Cursor and reproduce — confirms it isn’t transient session state.
  • Try a different repo or different machine — separates Cursor config from project state.
  • Have a teammate open the same repo — confirms it isn’t only your local cache.

If it still fails

  • Reduce repro to one file, one AI apply, auto-save off.
  • Roll back the most recent Cursor upgrade or settings.json change.
  • Search forum.cursor.com for “file watcher missed” / “out of sync”; include OS + filesystem.
  • Grab View → Output → Log (Window) and post to Bug Reports.

Prevention

  • Auto-save off during AI sessions; turn it back on after.
  • Don’t split-pane the same file; for comparisons use git diff / source control views.
  • Always keep projects on native filesystem: macOS APFS, WSL ext4, local Linux disk.
  • Add Cursor install path + project root to AV / Spotlight allowlists.
  • Commit before and after important AI sessions — worst case a single git reset --hard recovers.

Tags: #Troubleshooting #Cursor #Debug #IDE sync

Related Articles