siyuan-note/siyuan · error

--id is required

Error message

--id is required

What it means

The `document get` cobra subcommand requires the --id flag pointing to a block ID. The handler reads --id and returns this error when empty, before calling treenode.GetBlockTree. The ID must be a valid SiYuan block ID (typically a 14-digit timestamp + random suffix, e.g. 20240101000000-abc1234) that identifies a document root or child block.

Source

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

		fmt.Println(id)
		return nil
	},
}

func normalizeDocumentCreateParentPath(parentPath string) string {
	if "" == parentPath {
		return "/"
	}
	return strings.TrimSuffix(path.Clean(parentPath), ".sy")
}

var documentGetCmd = &cobra.Command{
	Use:   "get --id <id>",
	Short: "Get document info",
	RunE: func(cmd *cobra.Command, args []string) error {
		id, _ := cmd.Flags().GetString("id")
		if id == "" {
			return fmt.Errorf("--id is required")
		}
		bt := treenode.GetBlockTree(id)
		if bt == nil {
			return fmt.Errorf("document not found: %s", id)
		}

		tree, err := model.LoadTreeByBlockID(id)
		if err != nil {
			return err
		}
		block, err := model.GetBlock(id, tree)
		if err != nil {
			return err
		}

		switch outputFormat {
		case "json":
			data, _ := json.MarshalIndent(block, "", "  ")

View on GitHub (pinned to 251596fc0d)

Solutions

1. Supply the document/block ID: `siyuan document get --id 20240101000000-abc1234`.
2. Obtain the ID via `siyuan document list --notebook <id>` or `siyuan document search <keyword>`.
3. Trim whitespace in scripts: `--id "$(echo $id | tr -d '[:space:]')".
4. Verify the flag name with `siyuan document get --help`.

Example fix

// before
siyuan document get
// after
siyuan document get --id 20240101000000-abc1234

[ -n "$DOC_ID" ] || { echo '--id is required' >&2; exit 2; }
siyuan document get --id "$DOC_ID"

// Go: SiYuan block IDs match this shape
var blockIDRe = regexp.MustCompile(`^\d{14}-[a-z0-9]+$`)
func isValidBlockID(id string) bool { return blockIDRe.MatchString(id) }

if ! siyuan document get --id "$DOC_ID" 2>err.txt; then
  grep -qE 'id is required|not found' err.txt && echo "check --id (try: siyuan document search <keyword>)" >&2
  exit 1
fi

When it happens

Trigger: Running `siyuan document get` with no flags; passing `--id ""`; misspelling the flag; copying a truncated ID from a URL; scripting with an unset ID variable.

Common situations: Forgetting the ID after switching context; assuming positional ID argument support; passing the document title instead of its ID; referencing a shell variable that was never populated; trailing whitespace in the ID.

Related errors

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

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