What causes "template document tree output exceeds %d bytes" in siyuan-note/siyuan?

Reduce the amount of content the template renders (limit range loops, trim large sections)

template document tree output exceeds %d bytes

Error message

template document tree output exceeds %d bytes

What it means

renderTemplateDocTreeNodes accumulates the byte length of every rendered template node and enforces maxTemplateDocTreeOutputSize as a hard cap on total generated output. When the aggregate rendered markdown from all nodes exceeds this limit, rendering is aborted with this error to prevent unbounded memory/document growth from a runaway template.

Source

Thrown at kernel/model/template_doc_tree_render.go:45

	"github.com/88250/lute/ast"
	"github.com/88250/lute/parse"
	"github.com/siyuan-note/siyuan/kernel/av"
	"github.com/siyuan-note/siyuan/kernel/sql"
	"github.com/siyuan-note/siyuan/kernel/treenode"
	"github.com/siyuan-note/siyuan/kernel/util"
)

func renderTemplateDocTreeNodes(collector *templateDocTreeCollector, rootTemplate *template.Template,
	funcs template.FuncMap) error {
	for _, node := range flattenTemplateDocTreeNodes0(collector.nodes) {
		content, err := renderTemplateDocTreeNodeContent(collector, rootTemplate, funcs, node)
		if nil != err {
			return err
		}
		collector.totalOutput += len(content)
		if maxTemplateDocTreeOutputSize < collector.totalOutput {
			return fmt.Errorf("template document tree output exceeds %d bytes", maxTemplateDocTreeOutputSize)
		}
		tree, err := renderTemplateDocTreeMarkdown(content, collector.boxID)
		if nil != err {
			return err
		}
		collector.buildTree(node, tree)
	}
	return nil
}

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

View on GitHub (pinned to 8641553a1f)

Solutions

Reduce the amount of content the template renders (limit range loops, trim large sections)
Split the template into several smaller template document tree invocations
Cap loop iterations with template logic (e.g. slice/index limits) before rendering
If the limit is legitimately too small for your use case, raise maxTemplateDocTreeOutputSize in the kernel and rebuild

Example fix

// before
.action{range .items}...full row content...{.action end}
// after: cap iterations
.action{range $i, $v := .items}{if lt $i 100}...row...{end}{end}

Defensive patterns

Strategy: validation

Validate before calling

const maxTemplateDocTreeOutputSize = 1 << 20 // match kernel constant
if estimateTemplateOutputBytes(nodes) > maxTemplateDocTreeOutputSize {
	return errors.New("template output would exceed the kernel's aggregate output limit")
}

Prevention

Cap range-loop iterations inside child templates before shipping them
Estimate rendered size (e.g. dry-run render in a test) for large templates
Split very large template document trees into multiple smaller ones

When it happens

Trigger: A template document tree whose child templates (node.Template files or node.Define definitions) collectively render more bytes than maxTemplateDocTreeOutputSize — e.g. a .action{range ...} loop over a large dataset inside a child template, or many nodes each rendering large content.

Common situations: Range loops iterating thousands of rows in a child template; deeply nested doc-tree templates each emitting large sections; importing a template package designed for a single doc into a multi-node doc tree.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

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