{"record":{"id":"0f8485e1dcd173e2","repo":"siyuan-note/siyuan","slug":"not-a-valid-workspace-s","errorCode":null,"errorMessage":"not a valid workspace: %s","messagePattern":"not a valid workspace: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"kernel/cli/cmd/root.go","lineNumber":90,"sourceCode":"\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\"\n\t\tutil.InitWorkspace(workspacePath, util.WorkingDir)\n\n\t\tlogging.SetLogPath(filepath.Join(util.TempDir, \"siyuan-cli.log\"))\n\t\tlogging.SetLogToStdout(false)\n\n\t\t// CLI 单次命令默认 warn 级别（siyuan-cli.log 只保留警告及以上），避免内核初始化的大量 Info/Debug 日志噪声；\n\t\t// 用户可通过 --log-level 显式覆盖。把级别记入 util.CLILogLevel，使随后的 model.InitConf 不再用 conf.json 覆盖。\n\t\t// 注意 serve 子命令走自己的 PersistentPreRunE，不受此默认值影响，仍跟随 conf.json 的 system.logLevel。\n\t\teffectiveLevel := logLevel\n\t\tif \"\" == effectiveLevel {\n\t\t\teffectiveLevel = \"warn\"\n\t\t}\n\t\tlogging.SetLogLevel(effectiveLevel)\n\t\tutil.CLILogLevel = effectiveLevel\n","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/kernel/cli/cmd/root.go#L72-L108","documentation":"Thrown in `rootCmd.PersistentPreRunE` when the workspace directory exists on disk but fails `util.IsWorkspaceDir(workspacePath)`. SiYuan requires a workspace to look like a valid data root (it must be a writable directory that is not a system/temp/network path and not the user's home root). This guard prevents the kernel from initializing databases and indexes against an unsuitable directory that could corrupt data or hang on special filesystems.","triggerScenarios":"Pointing `--workspace` at `~`, `/tmp`, a network mount root, a non-directory path, or a directory already locked/used by another process; pointing at a folder that lacks the expected SiYuan data layout markers.","commonSituations":"Setting `--workspace ~` by mistake; sharing a workspace over a network filesystem that `IsWorkspaceDir` rejects; pointing at a folder from a different/older SiYuan version whose layout no longer validates; a leftover `.siyuan` lock from a crashed process.","solutions":["Use a dedicated SiYuan workspace directory (the default `~/SiYuan` or a fresh empty dir).","Check `util.IsWorkspaceDir` criteria — avoid home root, temp dirs, and network mounts.","Remove stale lock files if a previous process crashed, then retry.","If upgrading across major versions, let the GUI app migrate the workspace once before using the CLI."],"exampleFix":"// before\nsiyuan --workspace ~ search foo\n// after\nsiyuan --workspace ~/SiYuan search foo","handlingStrategy":"validation","validationCode":"// Beyond existence, ensure the dir is a valid SiYuan workspace.\nif !util.IsWorkspaceDir(workspacePath) {\n    log.Fatalf(\"not a valid SiYuan workspace: %s\", workspacePath)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use a dedicated workspace directory, never home root, /tmp, or a network mount.","Let the GUI app initialize/migrate a workspace before CLI use.","Clear stale `.siyuan` locks from crashed processes."],"tags":["cli","bootstrap","workspace","validation","filesystem"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}