siyuan-note/siyuan · error

renderDocRef children target must be a document ID

Error message

renderDocRef children target must be a document ID

What it means

In renderDocRef "children" mode, the target value must be a document ID string — either the root document ID or the ID of a node in the collected doc tree. If the value is not a string (number, object, etc.), the call fails with "renderDocRef children target must be a document ID".

Source

Thrown at kernel/model/template_doc_tree.go:249

func (collector *templateDocTreeCollector) bindNodes(nodes []*TemplateDocTreeNode, parentID, parentPath, parentHPath string) {
	for _, node := range nodes {
		node.ParentID = parentID
		node.path = strings.TrimSuffix(parentPath, ".sy") + "/" + node.ID + ".sy"
		node.HPath = path.Join(parentHPath, node.Title)
		collector.bindNodes(node.Children, node.ID, node.path, node.HPath)
	}
}

func (collector *templateDocTreeCollector) renderDocRef(mode string, value any) (any, error) {
	if !collector.enabled {
		return nil, errors.New("renderDocRef is only available when manually inserting or previewing a template")
	}
	switch mode {
	case "children":
		id, ok := value.(string)
		if !ok {
			return nil, errors.New("renderDocRef children target must be a document ID")
		}
		if collector.rootID == id {
			return collector.nodes, nil
		}
		for _, node := range flattenTemplateDocTreeNodes0(collector.nodes) {
			if node.ID == id {
				return node.Children, nil
			}
		}
		return []*TemplateDocTreeNode{}, nil
	case "path":
		hPath, ok := value.(string)
		if !ok {
			return "", errors.New("renderDocRef path target must be a document path")
		}
		requestedPath := path.Clean(hPath)
		for _, node := range flattenTemplateDocTreeNodes0(collector.nodes) {
			relativePath := strings.TrimPrefix(node.HPath, collector.rootHPath)

View on GitHub (pinned to 8641553a1f)

Solutions

1. Quote the ID: renderDocRef("children", "20240101120000-abcdefg").
2. Coerce the variable to a string before passing (e.g. string formatting in the template).
3. Verify the target exists: unknown string IDs return an empty list rather than erroring, so only type errors raise this.

Example fix

// before
renderDocRef("children", 20240101120000)
// after
renderDocRef("children", "20240101120000-abcdefg")

if (typeof target !== "string" || target.length === 0) throw new Error("children target must be a document ID string");

const isDocID = (v) => typeof v === "string" && /^\d{14}-[0-9a-z]{7}$/.test(v);

try {
  const kids = renderDocRef("children", target);
} catch (e) {
  if (String(e).includes("must be a document ID")) {
    // coerce target to a string and retry
  }
}

When it happens

Trigger: Calling renderDocRef("children", 123) or renderDocRef("children", someObject) from a template, e.g. passing a numeric ID or forgetting to quote the value.

Common situations: Template syntax where IDs look numeric and were written unquoted; passing a variable that holds a non-string; mixing up title/path with ID.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• renderDocRef path target must be a document path
• new item template field [%s] current time value is invalid
• new item template field [%s] value is invalid
• createDocTree definition must be a list
• createDocTree document must be a dictionary

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/6f1783bf746f69a2. Report an issue: GitHub.