What causes "directory not found: %s" in siyuan-note/siyuan?

Create the workspace first by launching the SiYuan app once, or pass -w pointing at an existing workspace directory.

directory not found

Error message

directory not found: %s

What it means

After resolving the workspace path (in order: --workspace/-w flag, SIYUAN_WORKSPACE_PATH env var, then ~/SiYuan default), the CLI stats the directory before initializing it. If the path does not exist on disk, the command aborts with this error. The CLI requires an existing workspace; it never creates one implicitly.

Solutions

Create the workspace first by launching the SiYuan app once, or pass -w pointing at an existing workspace directory.
Check the SIYUAN_WORKSPACE_PATH environment variable value and correct or unset it if it points to a stale path.
Verify the exact spelling/case of the path (`ls <path>`); fix the -w argument accordingly.
If the workspace was moved, update the -w flag or env var to the new location.

Example fix

// before
export SIYUAN_WORKSPACE_PATH=/Users/me/Documents/SiYuan-old
SiYuan-Kernel search -m 4
// after
export SIYUAN_WORKSPACE_PATH=/Users/me/SiYuan   # existing directory
SiYuan-Kernel search -m 4

Defensive patterns

Strategy: validation

Validate before calling

# Shell: verify workspace exists before calling the CLI
if [ ! -d "$SIYUAN_WORKSPACE_PATH" ]; then echo "workspace missing: $SIYUAN_WORKSPACE_PATH"; exit 1; fi

Try / catch

if err := runKernelCLI(args); err != nil && strings.HasPrefix(err.Error(), "directory not found") {
    // create/initialize workspace (launch the app once) or fix -w before retry
}

Prevention

Store the workspace path in one scripted variable and validate it with a stat before every CLI invocation.
Avoid relying on the ~/SiYuan default in automation; always pass an explicit -w.
After moving or syncing a workspace, re-check the path before running CLI commands.

When it happens

Trigger: Running e.g. `SiYuan-Kernel search ... -w /path/to/ws` or with SIYUAN_WORKSPACE_PATH set to a path that does not exist, and no -w flag override. Also occurs when the default ~/SiYuan was never created (fresh machine) and any non-workspace subcommand is run.

Common situations: Typo in the -w value or in SIYUAN_WORKSPACE_PATH; pointing at a workspace deleted or moved after a sync/migration; running the CLI on a machine where SiYuan has never been launched (no ~/SiYuan); Windows/macOS path-case mismatches; container mounts missing the volume.

Related errors

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

Appendix: source

Thrown at kernel/cli/cmd/root.go:87

		if workingDir := resolveWorkingDir(); workingDir != "" {
			util.WorkingDir = workingDir
		}

		langsDir := filepath.Join(util.WorkingDir, "appearance", "langs")
		if _, err := os.Stat(langsDir); os.IsNotExist(err) {
			return fmt.Errorf("appearance files not found at [%s]", langsDir)
		}

		// 设置工作空间路径
		if workspacePath == "" {
			workspacePath = os.Getenv("SIYUAN_WORKSPACE_PATH")
		}
		if workspacePath == "" {
			workspacePath = filepath.Join(util.HomeDir, "SiYuan")
		}

		if _, err := os.Stat(workspacePath); os.IsNotExist(err) {
			return fmt.Errorf("directory not found: %s", workspacePath)
		}
		if !util.IsWorkspaceDir(workspacePath) {
			return fmt.Errorf("not a valid workspace: %s", workspacePath)
		}

		util.Mode = "prod"
		util.InitWorkspace(workspacePath, util.WorkingDir)

		logging.SetLogPath(filepath.Join(util.TempDir, "siyuan-cli.log"))
		logging.SetLogToStdout(false)

		// CLI 单次命令默认 warn 级别（siyuan-cli.log 只保留警告及以上），避免内核初始化的大量 Info/Debug 日志噪声；
		// 用户可通过 --log-level 显式覆盖。把级别记入 util.CLILogLevel，使随后的 model.InitConf 不再用 conf.json 覆盖。
		// 注意 serve 子命令走自己的 PersistentPreRunE，不受此默认值影响，仍跟随 conf.json 的 system.logLevel。
		effectiveLevel := logLevel
		if "" == effectiveLevel {
			effectiveLevel = "warn"
		}

View on GitHub (pinned to 9f775e8a12)