{"record":{"id":"0a738c489fb3a09d","repo":"siyuan-note/siyuan","slug":"appearance-files-not-found-at-s","errorCode":null,"errorMessage":"appearance files not found at [%s]","messagePattern":"appearance files not found at \\[(.+?)\\]","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/cli/cmd/root.go","lineNumber":75,"sourceCode":"\t\tsql.FlushQueue()\n\t\treturn nil\n\t},\n\tPersistentPreRunE: func(cmd *cobra.Command, args []string) error {\n\t\t// workspace 子命令不需要工作空间校验\n\t\tif cmd.Parent() != nil && cmd.Parent().Name() == \"workspace\" {\n\t\t\treturn nil\n\t\t}\n\n\t\t// 默认工作目录取内核可执行文件所在目录的上一级（打包后的 resources/，appearance/、stage/ 所在目录），\n\t\t// 而非内核可执行文件所在目录本身（resources/kernel/）。resolveWorkingDir() 会校验 appearance/langs 实际存在，\n\t\t// 兼容开发态等多种目录布局。\n\t\tif workingDir := resolveWorkingDir(); workingDir != \"\" {\n\t\t\tutil.WorkingDir = workingDir\n\t\t}\n\n\t\tlangsDir := filepath.Join(util.WorkingDir, \"appearance\", \"langs\")\n\t\tif _, err := os.Stat(langsDir); os.IsNotExist(err) {\n\t\t\treturn fmt.Errorf(\"appearance files not found at [%s]\", langsDir)\n\t\t}\n\n\t\t// 设置工作空间路径\n\t\tif workspacePath == \"\" {\n\t\t\tworkspacePath = os.Getenv(\"SIYUAN_WORKSPACE_PATH\")\n\t\t}\n\t\tif workspacePath == \"\" {\n\t\t\tworkspacePath = filepath.Join(util.HomeDir, \"SiYuan\")\n\t\t}\n\n\t\tif _, err := os.Stat(workspacePath); os.IsNotExist(err) {\n\t\t\treturn fmt.Errorf(\"directory not found: %s\", workspacePath)\n\t\t}\n\t\tif !util.IsWorkspaceDir(workspacePath) {\n\t\t\treturn fmt.Errorf(\"not a valid workspace: %s\", workspacePath)\n\t\t}\n\n\t\tutil.Mode = \"prod\"","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/9f775e8a12daef8255556097396f9b2739078892/kernel/cli/cmd/root.go#L57-L93","documentation":"The SiYuan CLI kernel binary validates before running any subcommand (except workspace) that an appearance/langs directory exists under the resolved working directory. resolveWorkingDir() probes candidate directories relative to the executable (resources/, app/, macOS bundle Resources) and falls back to util.WorkingDir; if none of them contains appearance/langs, this error aborts the command. It protects UI/i18n-dependent operations from running against an incomplete or mis-deployed installation.","triggerScenarios":"Running any rootCmd subcommand whose PersistentPreRunE executes (i.e. not under the workspace subcommand) when os.Stat(filepath.Join(util.WorkingDir, \"appearance\", \"langs\")) reports the directory does not exist — e.g. the kernel binary was copied out of its install tree, or a custom build of SiYuan-Kernel was placed in a bare directory.","commonSituations":"Downloading SiYuan-Kernel alone without the resources/appearance folder; moving the binary to /usr/local/bin or another isolated path; running a self-compiled kernel from kernel/ without the app/ layout; symlinked or containerized deployments that copy only the executable; macOS installs where the bundle Resources layout changed.","solutions":["Install the kernel binary in the expected layout so its parent directory contains appearance/langs (production: resources/kernel/SiYuan-Kernel with resources/appearance/).","Re-download/reinstall the full SiYuan package instead of just the kernel executable.","Run the binary from a checkout that includes app/appearance/langs (resolveWorkingDir probes kernel/ → app/ and exeDir/app), e.g. build to kernel/ of the repo.","Verify the path printed in the error actually lacks appearance/langs and create/copy that directory there if it is a custom deployment you control."],"exampleFix":"// before: copying only the binary\ncp SiYuan-Kernel /opt/siyuan/\n// after: keep the resources layout\ncp -r resources /opt/siyuan/   # contains kernel/SiYuan-Kernel and appearance/langs","handlingStrategy":"validation","validationCode":"// Go: check appearance files before invoking the CLI binary\nlangsDir := filepath.Join(installDir, \"appearance\", \"langs\")\nif fi, err := os.Stat(langsDir); err != nil || !fi.IsDir() {\n    return fmt.Errorf(\"kernel install incomplete: %s missing\", langsDir)\n}","typeGuard":null,"tryCatchPattern":"if err := runKernelCLI(args); err != nil && strings.Contains(err.Error(), \"appearance files not found\") {\n    // repair installation or reinstall before retrying\n}","preventionTips":["Always deploy the kernel with its full resources/ layout (kernel binary + appearance/), never copy the bare executable.","Smoke-test `SiYuan-Kernel --help` (or any cheap subcommand) after moving or packaging the binary.","Pin installs to a packaging script that copies appearance/langs alongside the kernel binary."],"tags":["cli","deployment","missing-files"],"backgroundTag":"file-not-found","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"}