{"record":{"id":"64caf800d02e5b95","repo":"siyuan-note/siyuan","slug":"symbolic-links-in-notebook-are-not-supported-s","errorCode":null,"errorMessage":"symbolic links in notebook are not supported: %s","messagePattern":"symbolic links in notebook are not supported: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/model/asset_relink.go","lineNumber":137,"sourceCode":"\t\t}\n\t\tboxID := entry.Name()\n\t\tif !entry.IsDir() || !ast.IsNodeIDPattern(boxID) {\n\t\t\tcontinue\n\t\t}\n\t\tif IsEncryptedBox(boxID) {\n\t\t\tp.result.SkippedNotebooks = append(p.result.SkippedNotebooks, boxID)\n\t\t\tcontinue\n\t\t}\n\t\tboxDir := filepath.Join(util.DataDir, boxID)\n\t\terr = filepath.WalkDir(boxDir, func(absPath string, entry fs.DirEntry, walkErr error) error {\n\t\t\tif walkErr != nil {\n\t\t\t\treturn walkErr\n\t\t\t}\n\t\t\tif err := p.checkContext(); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\tif entry.Type()&os.ModeSymlink != 0 {\n\t\t\t\treturn fmt.Errorf(\"symbolic links in notebook are not supported: %s\", absPath)\n\t\t\t}\n\t\t\tif entry.IsDir() {\n\t\t\t\tif err := p.observe(absPath); err != nil {\n\t\t\t\t\treturn err\n\t\t\t\t}\n\t\t\t\tif entry.Name() == \"assets\" {\n\t\t\t\t\tassetRoots = append(assetRoots, absPath)\n\t\t\t\t\treturn filepath.SkipDir\n\t\t\t\t}\n\t\t\t\tif strings.HasPrefix(entry.Name(), \".\") || entry.Name() == \"storage\" {\n\t\t\t\t\treturn filepath.SkipDir\n\t\t\t\t}\n\t\t\t\treturn nil\n\t\t\t}\n\t\t\tif !strings.HasSuffix(entry.Name(), \".sy\") {\n\t\t\t\treturn nil\n\t\t\t}\n\t\t\tif err := p.observe(absPath); err != nil {","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/9f775e8a12daef8255556097396f9b2739078892/kernel/model/asset_relink.go#L119-L155","documentation":"During the notebook scan, the directory walk encounters a filesystem entry whose mode includes os.ModeSymlink. The relink engine refuses to scan notebooks containing symbolic links because symlinks can point outside the notebook, making reference scanning and asset resolution unreliable and unsafe.","triggerScenarios":"Running FindAssetReferences/RelinkAsset on a notebook directory tree that contains any symlink (file or directory) anywhere the walker traverses, e.g. a symlinked assets subdirectory or a symlinked .sy document; entry.Type()&os.ModeSymlink != 0 triggers the error with the absolute path.","commonSituations":"Sync tools (Dropbox, git with symlinked files, rsync -s) created symlinks inside data/; a developer linked a shared assets folder into a notebook; restoring a workspace backup on a filesystem (Windows FAT/exFAT) that materialized links oddly.","solutions":["Find the offending symlink at the reported absolute path and remove it, replacing it with a real copy of the target if needed.","Re-run the relink with dryRun=true to confirm no other symlinks remain (the scan stops at the first one).","Exclude symlinked content from the notebook, or move shared assets into a location the scan supports.","Avoid tools that create symlinks inside the SiYuan data directory (e.g. use hard copies or the app's own sync)."],"exampleFix":"// before (shell)\nln -s /shared/assets data/notebooks/xxx/assets/shared\n// after (shell)\ncp -r /shared/assets data/notebooks/xxx/assets/shared","handlingStrategy":"validation","validationCode":"filepath.WalkDir(boxDir, func(p string, d fs.DirEntry, err error) error {\n    if d != nil && d.Type()&os.ModeSymlink != 0 {\n        return fmt.Errorf(\"symlink found: %s\", p)\n    }\n    return nil\n})","typeGuard":null,"tryCatchPattern":"if err := runRelink(); err != nil {\n    var pathErr *os.PathError\n    if strings.HasPrefix(err.Error(), \"symbolic links in notebook\") {\n        // prompt user to remove the symlink at the reported path and retry\n    }\n}","preventionTips":["Do not symlink files or folders into data/notebooks","Avoid sync tools that materialize symlinks in the workspace","Scan the notebook for symlinks before running relink operations"],"tags":["filesystem","symlink","asset-relink"],"backgroundTag":"unsupported-operation","analyzedSha":"9f775e8a12daef8255556097396f9b2739078892","analyzedAt":"2026-09-19T03:17:15.984Z","contentChangedAt":"2026-09-19T03:17:15.984Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}