siyuan-note/siyuan · error

target human-readable path not found: %s

Error message

target human-readable path not found: %s

What it means

The `document move` path-resolution helper resolveDocumentMovePath calls a `lookup(targetHPath)` to translate a human-readable path (e.g. /Parent/Child) into a concrete .sy path inside the destination notebook. When lookup finds no matching entry — i.e. no document/folder with that human-readable path exists in the target notebook — the helper returns this error. It fires after --id and --notebook pass, during target-path computation, so it is a data/lookup error rather than a flag error.

Source

Thrown at kernel/cli/cmd/document.go:344

	}

	targetHPath := path.Clean("/" + strings.TrimPrefix(hpath, "/"))
	if "/" == targetHPath {
		return "/", nil
	}

	sourceTitle := path.Base(path.Clean(sourceHPath))
	if sourceTitle == path.Base(targetHPath) {
		targetHPath = path.Dir(targetHPath)
		if "/" == targetHPath {
			return "/", nil
		}
	}

	if targetPath, found := lookup(targetHPath); found {
		return targetPath, nil
	}
	return "", fmt.Errorf("target human-readable path not found: %s", targetHPath)
}

var documentSearchCmd = &cobra.Command{
	Use:   "search <keyword>",
	Short: "Search documents by keyword",
	Args:  cobra.MinimumNArgs(1),
	RunE: func(cmd *cobra.Command, args []string) error {
		keyword := args[0]
		if keyword == "" {
			return fmt.Errorf("keyword is required")
		}
		docs := model.SearchDocs(keyword, false, nil)
		switch outputFormat {
		case "json":
			data, _ := json.MarshalIndent(docs, "", "  ")
			fmt.Println(string(data))
		default:
			if len(docs) == 0 {

View on GitHub (pinned to 251596fc0d)

Solutions

1. Create the target parent document/folder in the destination notebook first (via `document create`), then retry the move.
2. Verify the target human-readable path exists: `siyuan document list --notebook <dest> --hpath <parent>` and confirm it appears.
3. Omit --hpath to let the document move to the notebook root, or pass a --path (concrete .sy path) instead of an hpath if you know it.
4. Check the exact spelling, case, and slash structure of --hpath against the destination's hierarchy.
5. Ensure the destination notebook is open and indexed before moving.

Example fix

// before
siyuan document move --id <id> --notebook <dest> --hpath /Nonexistent/Parent
// after
# create the parent folder first, then move
siyuan document create --notebook <dest> --title Parent
siyuan document move --id <id> --notebook <dest> --hpath /Parent

# ensure the target human-readable path exists in the destination notebook before moving
siyuan document list --notebook "$DEST_NB" --hpath "$(dirname "$HPATH")" | grep -q . || { echo "target hpath not found; create parent first" >&2; exit 2; }
siyuan document move --id "$DOC_ID" --notebook "$DEST_NB" --hpath "$HPATH"

// Go: check the destination hierarchy contains the parent before resolving
func hpathExistsInNotebook(notebookID, hpath string) bool {
    files, _, err := model.ListDocTree(notebookID, hpath, 0, false, false, 128)
    return err == nil && len(files) > 0
}

if ! siyuan document move --id "$DOC_ID" --notebook "$DEST_NB" --hpath "$HPATH" 2>err.txt; then
  grep -q 'human-readable path not found' err.txt && echo "create parent folder in destination first: siyuan document create --notebook $DEST_NB --title <Parent>" >&2
  exit 1
fi

When it happens

Trigger: Passing --hpath pointing to a folder path that does not exist in the destination notebook; moving a document whose source title collides with the target name and the parent directory in the target does not exist; using --hpath from a different notebook's hierarchy; typos or wrong separators in --hpath; the destination notebook being empty.

Common situations: Assuming the target parent folder exists when it does not; expecting --hpath to auto-create intermediate folders; workspace/notebook mismatch; the lookup table not yet indexed for the destination notebook; passing a leading/trailing slash inconsistently with how paths are stored.

Related errors

• --notebook is required
• document not found: %s
• --id and --notebook are required
• --title is required
• --id is required

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/d385b461c967f8e3. Report an issue: GitHub.