siyuan-note/siyuan · error

--id is required

Error message

--id is required

What it means

`siyuan template render` renders a template against an existing block identified by `--id`; the id is mandatory because RenderTemplate needs the target block to bind template variables. The command returns this error when the flag is missing or empty.

Solutions

1. Pass the block id: `siyuan template render --path tpl.md --id 20240101120000-abcdefg`
2. Copy the block id from SiYuan (block context menu > copy block ID) and verify it is non-empty
3. Check the preceding command that produces the id variable actually succeeded

Example fix

// before
siyuan template render --path tpl.md
// after
siyuan template render --path tpl.md --id 20240101120000-abcdefg

if [ -z "$BLOCK_ID" ]; then echo "--id is required" >&2; exit 2; fi
siyuan template render --path tpl.md --id "$BLOCK_ID"

if ! siyuan template render --path tpl.md --id "$ID"; then
  echo "render failed; verify block id and path" >&2
fi

When it happens

Trigger: Running `siyuan template render --path tpl.md` without `--id <block-id>`.

Common situations: Having a valid --path but forgetting the block id; using an id copied with trailing whitespace that got trimmed to empty; scripting where the id lookup failed upstream.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• --name is required
• --av and --ids are required
• --av, --key, --item and --value are required
• --block is required for non-detached rows
• --file is required

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

Appendix: source

Thrown at kernel/cli/cmd/template.go:127

			fmt.Printf("[dry-run] Would remove template: %s\n", p)
			return nil
		}
		if err := model.RemoveTemplate(abs); err != nil {
			return err
		}
		fmt.Println("ok")
		return nil
	},
}

var templateRenderCmd = &cobra.Command{
	Use:   "render --path <path> --id <id>",
	Short: "Render a template against a block (preview)",
	RunE: func(cmd *cobra.Command, args []string) error {
		p, _ := cmd.Flags().GetString("path")
		id, _ := cmd.Flags().GetString("id")
		if id == "" {
			return fmt.Errorf("--id is required")
		}
		abs, err := resolveTemplateAbs(p)
		if err != nil {
			return err
		}
		_, dom, err := model.RenderTemplate(abs, id, true)
		if err != nil {
			return err
		}
		fmt.Print(dom)
		return nil
	},
}

var templateSaveAsCmd = &cobra.Command{
	Use:   "save-as --id <id> --name <name>",
	Short: "Save a document as a template",
	RunE: func(cmd *cobra.Command, args []string) error {

View on GitHub (pinned to 9f775e8a12)