Upgrade Storage[Report] SOLVED: iCloud Sync Issues & "File Not Found" on Windows - The NFD/iCloud Filename Conflict
[Report] SOLVED: iCloud Sync Issues & "File Not Found" on Windows - The NFD/iCloud Filename Conflict (Zotero 8)
1. Environment & Setup
- OS: macOS 13.7.8 (Primary) & Windows 11 Pro 25H2 (Secondary)
- Zotero Version: 8.0.3 (x64)
- Data Directory: Local (Fresh Installation)
- Attachment Storage:** iCloud Drive via ZotMoov (Shared folder: `...\iCloudDrive\Family Share\LIBRARY\ZOTERO-REEN`)
- Key Extension: ZotMoov (1.2.26)
2. The Problem: "The 8-Second Filename Mismatch"
- Symptom:** Attachments added on Mac (with long Korean titles) were synced to iCloud, but after ~8 seconds, the filenames were forcibly truncated by the iCloud server.
- Result:** Zotero's database recorded the original long filename, while the actual file on iCloud became shorter. This caused a permanent "File Not Found" error on Windows, as the database link and physical filename no longer matched.
- Specific Trigger:** This was most severe with **Korean characters (NFD encoding)** combined with symbols like commas (`,`) or colons (`:`).
3. Root Cause: iCloud Server-Side Sanitization & NFD Encoding
- NFD Multiplier:** On macOS, Korean characters are decomposed (NFD), making each character occupy ~3 bytes. A 70-character title can exceed 200+ bytes.
- Server-Side Truncation:** If the total path (Folders + Filename) exceeds iCloud's hidden byte limit, the server forcibly "sanitizes" the filename after upload.
- Variable Threshold:** The safe limit depends on your folder depth. In my case (~4 folders deep), the "Magic Number" for filename safety was **36 characters**.
4. The Definitive Solution: Pre-emptive Truncation
Step 1: Implement the "Safe Zone" Renaming Template
I modified the Zotero 8 template to strip illegal characters and truncate the filename `before` iCloud could intervene. This ensures Zotero's DB and the physical file always share the same name.
Template Code:
{{ firstCreator replaceFrom=", " replaceTo=" " }} - {{ year }} - {{ title replaceFrom=" : " replaceTo=" " replaceFrom=": " replaceTo=" " replaceFrom=", " replaceTo=" " truncate="36" }}
(Note: Adjust the `truncate` value (e.g., 30 or 40) based on your specific directory depth.)*
Step 2: Force Rename via Zotero 8 UI
Instead of relying on auto-sync, I used the **dedicated "Rename from Parent Metadata" button in the right-side Item Pane**. This forces the database to record the sanitized, short filename immediately.
5. Final Recommendations for Non-English Users
1. Sanitize Everything: Strictly avoid commas, colons, and equals signs in templates.
2. Find Your Magic Number: If your filename changes ~8 seconds after upload, your `truncate` value is too high. Decrease it until the name remains stable.
3. Keep Paths Shallow: Deeper folder structures (Family Share, etc.) require even shorter filenames to stay within the total path limit.
4. Zotero 8 Workflow: The new Item Pane buttons are more reliable for ensuring metadata-to-file consistency than legacy context menus.
---
Shared to assist the Zotero community in optimizing cross-platform workflows with multi-byte characters and cloud sync.
1. Environment & Setup
- OS: macOS 13.7.8 (Primary) & Windows 11 Pro 25H2 (Secondary)
- Zotero Version: 8.0.3 (x64)
- Data Directory: Local (Fresh Installation)
- Attachment Storage:** iCloud Drive via ZotMoov (Shared folder: `...\iCloudDrive\Family Share\LIBRARY\ZOTERO-REEN`)
- Key Extension: ZotMoov (1.2.26)
2. The Problem: "The 8-Second Filename Mismatch"
- Symptom:** Attachments added on Mac (with long Korean titles) were synced to iCloud, but after ~8 seconds, the filenames were forcibly truncated by the iCloud server.
- Result:** Zotero's database recorded the original long filename, while the actual file on iCloud became shorter. This caused a permanent "File Not Found" error on Windows, as the database link and physical filename no longer matched.
- Specific Trigger:** This was most severe with **Korean characters (NFD encoding)** combined with symbols like commas (`,`) or colons (`:`).
3. Root Cause: iCloud Server-Side Sanitization & NFD Encoding
- NFD Multiplier:** On macOS, Korean characters are decomposed (NFD), making each character occupy ~3 bytes. A 70-character title can exceed 200+ bytes.
- Server-Side Truncation:** If the total path (Folders + Filename) exceeds iCloud's hidden byte limit, the server forcibly "sanitizes" the filename after upload.
- Variable Threshold:** The safe limit depends on your folder depth. In my case (~4 folders deep), the "Magic Number" for filename safety was **36 characters**.
4. The Definitive Solution: Pre-emptive Truncation
Step 1: Implement the "Safe Zone" Renaming Template
I modified the Zotero 8 template to strip illegal characters and truncate the filename `before` iCloud could intervene. This ensures Zotero's DB and the physical file always share the same name.
Template Code:
{{ firstCreator replaceFrom=", " replaceTo=" " }} - {{ year }} - {{ title replaceFrom=" : " replaceTo=" " replaceFrom=": " replaceTo=" " replaceFrom=", " replaceTo=" " truncate="36" }}
(Note: Adjust the `truncate` value (e.g., 30 or 40) based on your specific directory depth.)*
Step 2: Force Rename via Zotero 8 UI
Instead of relying on auto-sync, I used the **dedicated "Rename from Parent Metadata" button in the right-side Item Pane**. This forces the database to record the sanitized, short filename immediately.
5. Final Recommendations for Non-English Users
1. Sanitize Everything: Strictly avoid commas, colons, and equals signs in templates.
2. Find Your Magic Number: If your filename changes ~8 seconds after upload, your `truncate` value is too high. Decrease it until the name remains stable.
3. Keep Paths Shallow: Deeper folder structures (Family Share, etc.) require even shorter filenames to stay within the total path limit.
4. Zotero 8 Workflow: The new Item Pane buttons are more reliable for ensuring metadata-to-file consistency than legacy context menus.
---
Shared to assist the Zotero community in optimizing cross-platform workflows with multi-byte characters and cloud sync.