siyuan-note/siyuan · error

--id is required

Error message

--id is required

What it means

Returned by the `ref backlinks` subcommand when --id is empty. Backlink lookup via model.GetBacklink2 requires a source block ID.

Source

Thrown at kernel/cli/cmd/ref.go:41

	"text/tabwriter"

	"github.com/siyuan-note/siyuan/kernel/model"

	"github.com/spf13/cobra"
)

var refCmd = &cobra.Command{
	Use:   "ref",
	Short: "Backlinks and references",
}

var refBacklinksCmd = &cobra.Command{
	Use:   "backlinks --id <id>",
	Short: "Get backlinks for a block",
	RunE: func(cmd *cobra.Command, args []string) error {
		id, _ := cmd.Flags().GetString("id")
		if id == "" {
			return fmt.Errorf("--id is required")
		}

		keyword, _ := cmd.Flags().GetString("keyword")
		sortMode, _ := cmd.Flags().GetInt("sort")

		_, backlinks, _, count, _ := model.GetBacklink2(id, keyword, "", sortMode, 0, model.Conf.Editor.BacklinkContainChildren)

		switch outputFormat {
		case "json":
			data, _ := json.MarshalIndent(backlinks, "", "  ")
			fmt.Println(string(data))
		default:
			printPathTable(backlinks, false)
		}

		fmt.Printf("\n%d backlink(s)\n", count)
		return nil
	},

View on GitHub (pinned to 251596fc0d)

Solutions

1. Pass a valid block ID: `ref backlinks --id <block-id>`.
2. Obtain the block ID from the editor or `block` commands.

Example fix

# before
siyuan ref backlinks
# after
siyuan ref backlinks --id 202406011200-abcdef

[ -n "$BLOCK_ID" ] || { echo 'ref backlinks requires --id'; exit 1; }
siyuan ref backlinks --id "$BLOCK_ID"

n/a (CLI flag validation)

n/a

When it happens

Trigger: Running `ref backlinks` with no --id flag or `--id ""`, before GetBacklink2 is invoked.

Common situations: Omitting the flag, assuming a default block, or a script variable that resolved to empty.

Related errors

• --pattern is required
• --path is required
• --path is required
• --file is required
• --notebook is required

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