{"record":{"id":"8d1cc7aa90a148f0","repo":"siyuan-note/siyuan","slug":"invalid-utf-8-path","errorCode":null,"errorMessage":"invalid UTF-8 path","messagePattern":"invalid UTF-8 path","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"kernel/util/icloud_darwin.go","lineNumber":59,"sourceCode":"*/\nimport \"C\"\n\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":41,"sourceCodeEnd":64,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/kernel/util/icloud_darwin.go#L41-L64","documentation":"Raised only on macOS (darwin, non-ios build) inside isUbiquitousItem. The cgo helper siyuanIsUbiquitousItem returns -2 when [NSString stringWithUTF8String:path] yields nil, i.e. the Go string contains bytes that are not valid UTF-8. The function is checking whether the workspace path lives in iCloud.","triggerScenarios":"During workspace boot, isICloudPath calls ResolveLongestExistingParent then isUbiquitousItem on the longest existing parent path. If that path string holds invalid UTF-8 bytes, stringWithUTF8String returns nil and the helper returns -2. Reachable only on macOS builds.","commonSituations":"A workspace path constructed from a volume or folder name with legacy non-UTF-8 encoding (e.g. old HFS+ filenames, mis-decoded mount points); a path passed through a non-UTF-8 locale. Rare in practice because macOS APFS normalizes paths.","solutions":["Rename or relocate the workspace so its absolute path is valid UTF-8.","Mount the source volume with a UTF-8 locale so path bytes are decoded correctly.","This error is non-fatal: the caller (isICloudPath) logs it at debug level and falls back to a path-prefix iCloud check, so no action is strictly required."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Ensure the workspace path is valid UTF-8 before iCloud detection.\nif !utf8.ValidString(workspaceAbsPath) {\n    logging.LogDebugf(\"workspace path is not valid UTF-8, skipping iCloud check: %s\", workspaceAbsPath)\n    return\n}","typeGuard":null,"tryCatchPattern":"if isUbiquitous, err := isUbiquitousItem(existingPath); err != nil {\n    logging.LogDebugf(\"check iCloud status for path [%s] failed: %s\", existingPath, err)\n} else if isUbiquitous {\n    // warn and treat as iCloud\n}","preventionTips":["Keep workspace paths ASCII or valid UTF-8.","Mount external volumes with a UTF-8 locale.","Treat iCloud detection errors as non-fatal: the path-prefix fallback still runs."],"tags":["darwin","icloud","filesystem","utf-8","macos-only"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}