What causes "child template definition [%s] not found" in siyuan-note/siyuan?

Make node.Define exactly match an existing {{define "name"}} in the root template (check spelling and case)

child template definition [%s] not found

Error message

child template definition [%s] not found

What it means

When a doc-tree node specifies node.Define, the kernel expects that name to be a template definition ({{define "name"}} or .action{template ...} define) already parsed into the root template set. rootTemplate.Lookup returns nil when no such definition exists, so rendering of that node fails with this error before execution.

Source

Thrown at kernel/model/template_doc_tree_render.go:73

func renderTemplateDocTreeNodeContent(collector *templateDocTreeCollector, rootTemplate *template.Template,
	funcs template.FuncMap, node *TemplateDocTreeNode) ([]byte, error) {
	if "" == node.Template && "" == node.Define {
		return nil, nil
	}

	previousAllowCreation := collector.allowCreation
	collector.allowCreation = false
	defer func() {
		collector.allowCreation = previousAllowCreation
	}()

	buf := &bytes.Buffer{}
	buf.Grow(4096)
	dataModel := templateDocTreeDataModel(node)
	if "" != node.Define {
		if nil == rootTemplate.Lookup(node.Define) {
			return nil, fmt.Errorf("child template definition [%s] not found", node.Define)
		}
		if err := validateTemplateCallGraph(rootTemplate, node.Define); nil != err {
			return nil, err
		}
		if err := rootTemplate.ExecuteTemplate(buf, node.Define, dataModel); nil != err {
			return nil, fmt.Errorf(Conf.Language(44), err.Error())
		}
		return buf.Bytes(), nil
	}

	childPath, err := resolveTemplatePackageFile(collector.templatePath, node.Template)
	if nil != err {
		return nil, err
	}
	content, err := os.ReadFile(childPath)
	if nil != err {
		return nil, err
	}

View on GitHub (pinned to 8641553a1f)

Solutions

Make node.Define exactly match an existing {{define "name"}} in the root template (check spelling and case)
Add the missing {{define "..."}} block to the root template file
Ensure the file containing the define is actually loaded into the root template set before rendering
If the node should load an external file instead, clear Define and set node.Template to the file path

Example fix

// before: node.Define = "childSection" but template has
{{define "child-section"}}...{{end}}
// after: align names
{{define "childSection"}}...{{end}}  // or set node.Define = "child-section"

Defensive patterns

Strategy: validation

Validate before calling

if node.Define != "" && rootTemplate.Lookup(node.Define) == nil {
	return fmt.Errorf("define %q is not present in the root template set", node.Define)
}

Prevention

Keep define names in a shared constant/list referenced by both {{define}} and node.Define
Grep template files for {{define "..."}} names and validate node.Define against them at load time
Prefer node.Template file paths over Define unless the define is verified to exist

When it happens

Trigger: A TemplateDocTreeNode has Define set to a name that was never declared via {{define "..."}} in the root template, or the define name is misspelled / differs in case, or the template file containing the define failed to parse into the root set.

Common situations: Typo in the define name in the doc-tree config vs the {{define}} block; renaming a define without updating node.Define; the parent template file with the define was not included in the parsed root template.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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