What causes "child template [%s] is not a regular file" in siyuan-note/siyuan?

Point the child template reference at an actual file, not a directory (add the file name/extension)

child template [%s] is not a regular file

Error message

child template [%s] is not a regular file

What it means

resolveTemplatePackageFile resolves symlinks (EvalSymlinks), stats the real path, and requires the target to be a regular file. Directories, FIFOs, device files, or broken-stat targets produce this error naming the original relative path. Child templates must be readable regular files.

Source

Thrown at kernel/model/template_doc_tree.go:428

	packageRoot := templatesRoot
	if 1 < len(parts) {
		packageRoot = filepath.Join(templatesRoot, parts[0])
	}
	absPath := filepath.Join(packageRoot, cleanPath)
	if !gulu.File.IsSubPath(packageRoot, absPath) || !filelock.IsExist(absPath) {
		return "", fmt.Errorf("child template [%s] not found in the current template package", relativePath)
	}
	realRoot, err := filepath.EvalSymlinks(packageRoot)
	if nil != err {
		return "", err
	}
	realPath, err := filepath.EvalSymlinks(absPath)
	if nil != err {
		return "", err
	}
	info, err := os.Stat(realPath)
	if nil != err || !info.Mode().IsRegular() {
		return "", fmt.Errorf("child template [%s] is not a regular file", relativePath)
	}
	if !gulu.File.IsSubPath(realRoot, realPath) {
		return "", errors.New("child template path is outside the current template package")
	}
	return realPath, nil
}

func templateDocTreeDataModel(node *TemplateDocTreeNode) map[string]string {
	return map[string]string{
		"title":    node.Title,
		"id":       node.ID,
		"parentID": node.ParentID,
		"rootID":   node.RootID,
		"hPath":    node.HPath,
		"name":     "",
		"alias":    "",
	}
}

View on GitHub (pinned to 8641553a1f)

Solutions

Point the child template reference at an actual file, not a directory (add the file name/extension)
If a directory was created where the file should be, rename the directory and create the template file
Replace directory symlinks with a direct file reference inside the package
Re-extract or re-download the template package if packaging corrupted the file

Example fix

// before (template content)
{{childTemplate "partials"}}
// after
{{childTemplate "partials/header.md"}}

Defensive patterns

Strategy: validation

Validate before calling

// Go: ensure each referenced child template is a regular file
info, err := os.Stat(filepath.Join(pkgRoot, filepath.FromSlash(ref)))
isRegular := err == nil && info.Mode().IsRegular()

Try / catch

if _, err := resolveTemplatePackageFile(root, rel); err != nil && strings.Contains(err.Error(), "is not a regular file") {
    return fmt.Errorf("%q resolves to a directory or special file", rel)
}

Prevention

Reference files with their full name and extension, not the containing folder
Do not name directories the same as expected template files
Avoid symlinks to directories inside template packages
Validate package contents (files not dirs) after extraction or download

When it happens

Trigger: A child template path inside the package resolves to a directory (e.g. {{childTemplate "partials"}} where partials/ is a folder), or to a special file/symlink whose target is not a regular file.

Common situations: Template author forgets the file extension and references the containing folder; a package directory named like the template file; a symlink pointing to a directory; packaging scripts accidentally replacing a .md file with a directory during extraction.

Related errors

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