siyuan-note/siyuan · error

target human-readable path not found

Error message

target human-readable path not found: %s

What it means

resolvePathWithLookup maps a target human-readable path (hpath like "/foo/bar") to an internal path. If the path is not the root "/" and the supplied lookup callback cannot find a block-tree root for it, the resolver returns this error. It means the destination path does not correspond to any existing document hierarchy node in the given notebook.

Solutions

1. Verify the exact hpath exists in the destination notebook (check in the SiYuan UI or via document search) and correct spelling/case
2. Omit --hpath or use "/" to move to the notebook root, which is always valid
3. Ensure the destination notebook is open/indexed so its block tree is available; open it once in the UI if needed
4. Create the parent documents at the target path before moving

Example fix

// before
document move --id "$ID" --notebook "$BOX" --hpath "/Archive/Old Notes"  // path may not exist
// after
if ! siyuan document search "Old Notes" | grep -q Archive; then
  echo "target hpath does not exist; falling back to root"
fi
document move --id "$ID" --notebook "$BOX" --hpath "/Archive/Old Notes"

// Pre-check that the target hpath exists before moving
const exists = siyuanDocSearch(targetHPath.split("/").pop()) !== null;
if (!exists) {
  throw new Error(`Refusing to move: ${targetHPath} not found in notebook ${boxID}`);
}
await runCli(`document move --id ${docID} --notebook ${boxID} --hpath "${targetHPath}"`);

function isNonEmptyHPath(p) {
  return typeof p === "string" && p.startsWith("/") && !p.endsWith("/") && p.length > 1;
}

try {
  runCli(`document move --id ${id} --notebook ${box} --hpath "${hpath}"`);
} catch (e) {
  if (String(e).includes("target human-readable path not found")) {
    runCli(`document move --id ${id} --notebook ${box} --hpath "/"`); // fallback to root
  } else {
    throw e;
  }
}

When it happens

Trigger: Moving a document with `document move --hpath /Some/Missing/Path` where no document exists at that path in the destination notebook; typos in the hpath; hpath given with a trailing slash or wrong letter case; moving into a notebook whose index has not been built.

Common situations: Scripts hardcoding destination paths that were renamed or deleted; cross-notebook moves where the path exists in the source notebook but not the target; workspaces where the target notebook is new and not yet indexed.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• appearance files not found at
• asset path contains an unresolved symbolic link
• asset path resolves outside notebook assets directory
• --attr is required (format: name=value)
• --av and --ids are required

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

Appendix: source

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

	})
}

func resolvePathWithLookup(userPath, hpath string, lookup func(string) (string, bool)) (string, error) {
	if "" != userPath {
		return userPath, nil
	}
	if "" == hpath {
		return "/", nil
	}

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

func resolveDocumentMovePath(boxID, userPath, hpath, sourceHPath string) (string, error) {
	return resolveDocumentMovePathWithLookup(userPath, hpath, sourceHPath, func(targetHPath string) (string, bool) {
		bt := treenode.GetBlockTreeRootByHPath(boxID, targetHPath)
		if nil == bt {
			return "", false
		}
		return bt.Path, true
	})
}

func resolveDocumentMovePathWithLookup(
	userPath, hpath, sourceHPath string,
	lookup func(string) (string, bool),
) (string, error) {
	if "" != userPath {
		return userPath, nil

View on GitHub (pinned to 9f775e8a12)