{"record":{"id":"0c35c8af9cbdd6dd","repo":"siyuan-note/siyuan","slug":"heading-s-is-a-leaf-block-and-cannot-have-child","errorCode":null,"errorMessage":"heading [%s] is a leaf block and cannot have children; to place a block below this heading, pass previousID=<heading id> or previousID=<last block below the heading> instead of parentID","messagePattern":"heading \\[(.+?)\\] is a leaf block and cannot have children; to place a block below this heading, pass previousID=<heading id> or previousID=<last block below the heading> instead of parentID","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/treenode/blocktree.go","lineNumber":550,"sourceCode":"\treturn false\n}\n\n// CheckContainerParent 校验 parentID 指向的块是否允许接收子块。\n// 仅在“通过 parentID 定位插入/移动目标”（即不依赖 previousID/nextID）的场景下调用，\n// 因为一旦带 previousID/nextID，事务层走的是兄弟级 InsertAfter/InsertBefore，天然合法。\n// 返回 nil 表示合法；返回 error 时调用方应拒绝本次操作。\nfunc CheckContainerParent(parentID string) error {\n\tbt := GetBlockTree(parentID)\n\tif nil == bt {\n\t\treturn fmt.Errorf(\"parent block not found: %s\", parentID)\n\t}\n\tif IsContainerType(bt.Type) {\n\t\treturn nil\n\t}\n\tif \"h\" == bt.Type {\n\t\t// 标题是叶子块，其“子内容”在数据结构上实为后续兄弟节点（由 HeadingChildren 按层级推算）。\n\t\t// 把块挂成标题的 AST 子节点属于非法嵌套，应改用 previousID 定位。\n\t\treturn fmt.Errorf(\"heading [%s] is a leaf block and cannot have children; to place a block below this heading, pass previousID=<heading id> or previousID=<last block below the heading> instead of parentID\", parentID)\n\t}\n\treturn fmt.Errorf(\"block [%s] type %q is a leaf block and cannot have children; use previousID to place the block as its sibling instead\", parentID, bt.Type)\n}\n\n// CheckListItemNesting 校验 parentID 和 childID 是否形成“列表项直含列表项”的非法嵌套。\n// 嵌套列表的正确结构是 ListItem > List > ListItem，列表项不能直接作为另一个列表项的子块。\n// 仅在 move 场景调用（源和目标类型均已知）。\nfunc CheckListItemNesting(parentID, childID string) error {\n\tparentBt := GetBlockTree(parentID)\n\tchildBt := GetBlockTree(childID)\n\tif nil == parentBt || nil == childBt {\n\t\treturn nil // 查不到就放行，不阻塞未知场景\n\t}\n\tif \"i\" == parentBt.Type && \"i\" == childBt.Type {\n\t\treturn fmt.Errorf(\"a list-item cannot directly contain another list-item; to nest, first create a list (NodeList) under the outer list-item, then add the inner list-items to that list\")\n\t}\n\treturn nil\n}","sourceCodeStart":532,"sourceCodeEnd":568,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/kernel/treenode/blocktree.go#L532-L568","documentation":"Returned by CheckContainerParent when the resolved block's Type is \"h\" (heading). Headings are leaf blocks in SiYuan's data model — their apparent sub-content is actually following siblings computed via HeadingChildren, not AST children. Attaching a block as an AST child of a heading is illegal nesting.","triggerScenarios":"Calling a parentID-based insert or move with parentID set to a heading block id. CheckContainerParent is run by block insert/move in api/block_op.go, MCP tools/block.go, and cli/cmd/block.go.","commonSituations":"An integration assumes headings can be containers (common in DOM/HTML thinking) and passes the heading id as parentID; moving a block 'under' a heading via the wrong parameter.","solutions":["Use previousID=<heading id> to place the new block as the heading's first following sibling.","Or use previousID=<id of the last block currently below the heading> to append at the end of that heading's section.","Do not pass a heading id as parentID; CheckContainerParent will always reject it."],"exampleFix":"// before\nInsertBlock(parentID: headingID, data: block) // -> heading is a leaf block\n\n// after: place as sibling using previousID\nInsertBlock(previousID: headingID, data: block)","handlingStrategy":"validation","validationCode":"// Headings are leaf blocks; route heading-targeted placement through previousID.\nbt := treenode.GetBlockTree(parentID)\nif bt != nil && bt.Type == \"h\" {\n    return fmt.Errorf(\"heading %s is a leaf; use previousID instead of parentID\", parentID)\n}\nreturn treenode.CheckContainerParent(parentID)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never pass a heading id as parentID; use previousID=<heading id> or previousID=<last block below the heading>.","When building integrations, document this explicitly: headings' 'children' are following siblings.","Check bt.Type == \"h\" in your client before choosing parentID vs previousID."],"tags":["block","heading","nesting","validation","leaf"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}