siyuan-note/siyuan · warning

invalid UTF-8 path

Error message

invalid UTF-8 path

What it means

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.

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 251596fc0d)

Solutions

1. Rename or relocate the workspace so its absolute path is valid UTF-8.
2. Mount the source volume with a UTF-8 locale so path bytes are decoded correctly.
3. 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.

// Ensure the workspace path is valid UTF-8 before iCloud detection.
if !utf8.ValidString(workspaceAbsPath) {
    logging.LogDebugf("workspace path is not valid UTF-8, skipping iCloud check: %s", workspaceAbsPath)
    return
}

if isUbiquitous, err := isUbiquitousItem(existingPath); err != nil {
    logging.LogDebugf("check iCloud status for path [%s] failed: %s", existingPath, err)
} else if isUbiquitous {
    // warn and treat as iCloud
}

When it happens

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

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

Understand the failure class

• 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
• export source [%s] is not a regular file
• refuse to write decrypted asset inside workspace
• source is not an encrypted asset
• import task not found or expired

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/8d1cc7aa90a148f0. Report an issue: GitHub.