siyuan-note/siyuan · error

invalid document file

Error message

invalid document file [%s]

What it means

checkTreeFile stats the absolute .sy path and requires it to be a regular file. os.Stat errors are returned as-is; when the file exists but is not a regular file (directory, symlink to non-file, device, socket), this error is returned. It prevents tree loading from treating non-regular filesystem entries as documents.

Solutions

1. Inspect the path: if it is a directory, rename or remove it and restore the .sy file.
2. Restore the missing .sy document from sync, history, or backup.
3. Confirm the path passed to the loader points at the .sy file itself, not a parent directory.

Example fix

// before
LoadTreeWithFix(boxID, "/doc.sy", lute) // data/<box>/doc.sy is a directory
// after
// remove/rename the directory and restore the regular file doc.sy, then retry

const st = require("fs").statSync(absPath);
if (!st.isFile()) throw new Error(absPath + " is not a regular file");

if err := os.Stat(absPath); err != nil || !info.Mode().IsRegular() {
    // restore the .sy file before loading
}

When it happens

Trigger: LoadTreeWithFix or LoadTreeByData resolving to a path that is a directory named like a document (e.g. ".../doc.sy/" existing as a folder), a FIFO/socket, or a broken special file.

Common situations: A document path colliding with a directory of the same name; sync or third-party tools leaving directories where .sy files belong; odd filesystem entries created by mounting or backups.

Related errors

• asset must be a regular file
• asset path must be a file
• can not remove [ ] caused by it is not a dir
• Conf.Language(87)
• export artifact [ ] is a directory

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

Appendix: source

Thrown at kernel/filesys/tree.go:321

		if "" == title {
			title = "Untitled"
		}
		hPathBuilder.WriteString(title)
		hPathBuilder.WriteString("/")
	}
	hPathBuilder.WriteString(ret.Root.IALAttr("title"))
	ret.HPath = hPathBuilder.String()
	ret.Hash = treenode.NodeHash(ret.Root, ret, luteEngine)
	return
}

func checkTreeFile(absPath string) error {
	info, err := os.Stat(absPath)
	if err != nil {
		return err
	}
	if !info.Mode().IsRegular() {
		return fmt.Errorf("invalid document file [%s]", absPath)
	}
	return nil
}

// readParentDocIAL 区分父文档缺失与读取、认证、解析失败，只有缺失才允许补树。
func readParentDocIAL(absPath string) (map[string]string, error) {
	return readDocIAL(absPath, false)
}

func readDocIAL(absPath string, strict bool) (map[string]string, error) {
	boxID := docIALBoxID(absPath)
	dek, _, release, err := acquireCryptoLease(boxID)
	if err != nil {
		return nil, err
	}
	defer release()
	data, err := filelock.ReadFile(absPath)
	if err != nil {

View on GitHub (pinned to 9f775e8a12)