{"record":{"id":"6f1783bf746f69a2","repo":"siyuan-note/siyuan","slug":"renderdocref-children-target-must-be-a-document-id","errorCode":null,"errorMessage":"renderDocRef children target must be a document ID","messagePattern":"renderDocRef children target must be a document ID","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/model/template_doc_tree.go","lineNumber":249,"sourceCode":"\nfunc (collector *templateDocTreeCollector) bindNodes(nodes []*TemplateDocTreeNode, parentID, parentPath, parentHPath string) {\n\tfor _, node := range nodes {\n\t\tnode.ParentID = parentID\n\t\tnode.path = strings.TrimSuffix(parentPath, \".sy\") + \"/\" + node.ID + \".sy\"\n\t\tnode.HPath = path.Join(parentHPath, node.Title)\n\t\tcollector.bindNodes(node.Children, node.ID, node.path, node.HPath)\n\t}\n}\n\nfunc (collector *templateDocTreeCollector) renderDocRef(mode string, value any) (any, error) {\n\tif !collector.enabled {\n\t\treturn nil, errors.New(\"renderDocRef is only available when manually inserting or previewing a template\")\n\t}\n\tswitch mode {\n\tcase \"children\":\n\t\tid, ok := value.(string)\n\t\tif !ok {\n\t\t\treturn nil, errors.New(\"renderDocRef children target must be a document ID\")\n\t\t}\n\t\tif collector.rootID == id {\n\t\t\treturn collector.nodes, nil\n\t\t}\n\t\tfor _, node := range flattenTemplateDocTreeNodes0(collector.nodes) {\n\t\t\tif node.ID == id {\n\t\t\t\treturn node.Children, nil\n\t\t\t}\n\t\t}\n\t\treturn []*TemplateDocTreeNode{}, nil\n\tcase \"path\":\n\t\thPath, ok := value.(string)\n\t\tif !ok {\n\t\t\treturn \"\", errors.New(\"renderDocRef path target must be a document path\")\n\t\t}\n\t\trequestedPath := path.Clean(hPath)\n\t\tfor _, node := range flattenTemplateDocTreeNodes0(collector.nodes) {\n\t\t\trelativePath := strings.TrimPrefix(node.HPath, collector.rootHPath)","sourceCodeStart":231,"sourceCodeEnd":267,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/8641553a1f07374001902d3ce773285db1292b2d/kernel/model/template_doc_tree.go#L231-L267","documentation":"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\".","triggerScenarios":"Calling renderDocRef(\"children\", 123) or renderDocRef(\"children\", someObject) from a template, e.g. passing a numeric ID or forgetting to quote the value.","commonSituations":"Template syntax where IDs look numeric and were written unquoted; passing a variable that holds a non-string; mixing up title/path with ID.","solutions":["Quote the ID: renderDocRef(\"children\", \"20240101120000-abcdefg\").","Coerce the variable to a string before passing (e.g. string formatting in the template).","Verify the target exists: unknown string IDs return an empty list rather than erroring, so only type errors raise this."],"exampleFix":"// before\nrenderDocRef(\"children\", 20240101120000)\n// after\nrenderDocRef(\"children\", \"20240101120000-abcdefg\")","handlingStrategy":"type-guard","validationCode":"if (typeof target !== \"string\" || target.length === 0) throw new Error(\"children target must be a document ID string\");","typeGuard":"const isDocID = (v) => typeof v === \"string\" && /^\\d{14}-[0-9a-z]{7}$/.test(v);","tryCatchPattern":"try {\n  const kids = renderDocRef(\"children\", target);\n} catch (e) {\n  if (String(e).includes(\"must be a document ID\")) {\n    // coerce target to a string and retry\n  }\n}","preventionTips":["Always pass quoted, full-format SiYuan node IDs","Coerce numeric IDs to strings before calling","Store IDs in string columns/variables only"],"tags":["template","type-mismatch","argument"],"backgroundTag":"type-mismatch","analyzedSha":"8641553a1f07374001902d3ce773285db1292b2d","analyzedAt":"2026-09-11T16:08:28.414Z","contentChangedAt":"2026-09-11T16:08:28.414Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}