siyuan-note/siyuan · error

invalid UTF-8 path

Error message

invalid UTF-8 path

What it means

isUbiquitousItem on macOS calls the C helper siyuanIsUbiquitousItem with a UTF-8 encoded path to query iCloud (ubiquitous) resource status. The C layer returns -2 when the Go string cannot be converted to a valid C string, i.e. the path is not valid UTF-8. Go then surfaces this as "invalid UTF-8 path" instead of calling into Foundation with garbage data.

Solutions

1. Inspect the offending path and locate the invalid byte sequence (e.g. with utf8.ValidString)
2. Rename the file to a valid UTF-8 name (or restore it from a clean backup/sync copy)
3. Sanitize paths before passing them to iCloud checks — reject or transliterate non-UTF-8 names at ingestion time
4. If the file is unneeded, remove it so sync/iCloud scans no longer encounter it

Example fix

// before
isUbiquitousItem(rawPath) // rawPath contains invalid bytes
// after
if !utf8.ValidString(rawPath) {
    return fmt.Errorf("skipping non-UTF-8 path: %q", rawPath)
}
isUbiquitousItem(rawPath)

func validUTF8Path(p string) bool { return utf8.ValidString(p) }
// call before isUbiquitousItem

func isSafePath(p string) bool { return p != "" && utf8.ValidString(p) }

if err != nil && err.Error() == "invalid UTF-8 path" {
    // log and skip the path; offer to rename the file
}

When it happens

Trigger: Calling isUbiquitousItem (directly or via iCloud-related file checks) with a path containing invalid UTF-8 bytes — typically filenames created on other filesystems with legacy encodings, or paths built from corrupted/untrusted input.

Common situations: Syncing notebooks from Windows/FAT/exFAT volumes where filenames were stored in non-UTF-8 encodings; data imported from archives with mangled names; paths assembled from user input containing raw bytes; corrupted .sy-adjacent asset filenames.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to read iCloud file resource status
• 344
• 345
• access to sensitive workspace file is forbidden
• accessing assets in encrypted notebook

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

Appendix: source

Thrown at kernel/util/icloud_darwin.go:59

*/
import "C"

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)