{"record":{"id":"fde0818fd2db54d7","repo":"siyuan-note/siyuan","slug":"failed-to-read-icloud-file-resource-status","errorCode":null,"errorMessage":"failed to read iCloud file resource status","messagePattern":"failed to read iCloud file resource status","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/util/icloud_darwin.go","lineNumber":61,"sourceCode":"\nimport (\n\t\"errors\"\n\t\"unsafe\"\n)\n\nfunc isUbiquitousItem(path string) (bool, error) {\n\tcPath := C.CString(path)\n\tdefer C.free(unsafe.Pointer(cPath))\n\n\tswitch C.siyuanIsUbiquitousItem(cPath) {\n\tcase 1:\n\t\treturn true, nil\n\tcase 0:\n\t\treturn false, nil\n\tcase -2:\n\t\treturn false, errors.New(\"invalid UTF-8 path\")\n\tdefault:\n\t\treturn false, errors.New(\"failed to read iCloud file resource status\")\n\t}\n}\n","sourceCodeStart":43,"sourceCodeEnd":64,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/9f775e8a12daef8255556097396f9b2739078892/kernel/util/icloud_darwin.go#L43-L64","documentation":"isUbiquitousItem maps the C helper's return codes to Go results: 1/0 mean ubiquity status true/false, -2 is an encoding error, and any other negative code is reported as \"failed to read iCloud file resource status\". This means the underlying macOS API (e.g. NSURLUbiquitousItemDownloadingStatusKey lookup) failed for a reason other than encoding — file not found, permissions, or an Foundation/CoreServices error.","triggerScenarios":"Calling isUbiquitousItem with a path that does not exist in the iCloud container, a file the process cannot access, an item removed between listing and check, or an unexpected C-layer return code from the Objective-C resource query.","commonSituations":"iCloud Drive items evicted or deleted mid-scan; race between directory enumeration and item removal; insufficient Full Disk Access / iCloud permissions for the SiYuan process; the file lives outside the app's iCloud container so the resource query fails.","solutions":["Verify the path exists and re-check — transient races (file deleted during scan) are the most common cause; retry once","Grant the SiYuan process Full Disk Access / iCloud Drive access on macOS","Confirm the file is inside the app's iCloud (ubiquitous) container and signed into the same Apple ID","Check Console.app logs around siyuanIsUbiquitousItem for the underlying NSError description","Log out/in of iCloud or re-enable iCloud Drive if status queries persistently fail"],"exampleFix":"// before\nok, err := isUbiquitousItem(p) // fails: item deleted during scan\n// after\nok, err := isUbiquitousItem(p)\nif err != nil {\n    if _, statErr := os.Stat(p); os.IsNotExist(statErr) {\n        continue // item vanished; skip instead of failing the scan\n    }\n}","handlingStrategy":"fallback","validationCode":"if _, err := os.Stat(path); os.IsNotExist(err) { return fmt.Errorf(\"path vanished, skip\") }","typeGuard":null,"tryCatchPattern":"if err != nil && err.Error() == \"failed to read iCloud file resource status\" {\n    // retry once; if the file no longer exists, treat as non-ubiquitous and continue\n}","preventionTips":["Grant Full Disk Access / iCloud permissions to the app","Handle toctou races by tolerating per-item errors during scans","Keep macOS signed into iCloud Drive with the same Apple ID"],"tags":["icloud","macos","filesystem","darwin"],"backgroundTag":"file-read-failed","analyzedSha":"9f775e8a12daef8255556097396f9b2739078892","analyzedAt":"2026-09-19T03:17:15.984Z","contentChangedAt":"2026-09-19T03:17:15.984Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}