siyuan-note/siyuan · error

failed to read iCloud file resource status

Error message

failed to read iCloud file resource status

What it means

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.

Solutions

1. Verify the path exists and re-check — transient races (file deleted during scan) are the most common cause; retry once
2. Grant the SiYuan process Full Disk Access / iCloud Drive access on macOS
3. Confirm the file is inside the app's iCloud (ubiquitous) container and signed into the same Apple ID
4. Check Console.app logs around siyuanIsUbiquitousItem for the underlying NSError description
5. Log out/in of iCloud or re-enable iCloud Drive if status queries persistently fail

Example fix

// before
ok, err := isUbiquitousItem(p) // fails: item deleted during scan
// after
ok, err := isUbiquitousItem(p)
if err != nil {
    if _, statErr := os.Stat(p); os.IsNotExist(statErr) {
        continue // item vanished; skip instead of failing the scan
    }
}

if _, err := os.Stat(path); os.IsNotExist(err) { return fmt.Errorf("path vanished, skip") }

if err != nil && err.Error() == "failed to read iCloud file resource status" {
    // retry once; if the file no longer exists, treat as non-ubiquitous and continue
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• invalid UTF-8 path
• 345
• access to sensitive workspace file is forbidden
• accessing assets in encrypted notebook
• ambiguous asset path

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/fde0818fd2db54d7. Report an issue: GitHub.

Appendix: source

Thrown at kernel/util/icloud_darwin.go:61

import (
	"errors"
	"unsafe"
)

func isUbiquitousItem(path string) (bool, error) {
	cPath := C.CString(path)
	defer C.free(unsafe.Pointer(cPath))

	switch C.siyuanIsUbiquitousItem(cPath) {
	case 1:
		return true, nil
	case 0:
		return false, nil
	case -2:
		return false, errors.New("invalid UTF-8 path")
	default:
		return false, errors.New("failed to read iCloud file resource status")
	}
}

View on GitHub (pinned to 9f775e8a12)