What causes "createDocTree exceeds the maximum document count of %d" in siyuan-note/siyuan?

Split the definition into batches of at most 128 documents and invoke createDocTree multiple times.

createDocTree exceeds the maximum document count of

Error message

createDocTree exceeds the maximum document count of %d

What it means

A single createDocTree invocation is limited to maxTemplateDocTreeDocs (128) documents, counted across the whole definition tree. When parseNodes sees more than 128 entries in one definition, it aborts. The message interpolates the numeric limit.

Solutions

Split the definition into batches of at most 128 documents and invoke createDocTree multiple times.
Reduce generated entries (e.g. generate weekly rather than daily documents).
Generate documents via the kernel API in a loop instead of a single template action.

Example fix

// before
createDocTree(docs.slice(0, 300))
// after
for (let i = 0; i < docs.length; i += 128) {
  createDocTree(docs.slice(i, i + 128));
}

Defensive patterns

Strategy: validation

Validate before calling

function countDocs(nodes) {
  return nodes.reduce((n, d) => n + 1 + (d.children ? countDocs(d.children) : 0), 0);
}
if (countDocs(def) > 128) throw new Error('split into batches of <= 128');

Try / catch

try {
  createDocTree(def);
} catch (e) {
  if (String(e).includes("maximum document count")) {
    for (let i = 0; i < def.length; i += 100) createDocTree(def.slice(i, i + 100));
  }
}

Prevention

Count nested children too when checking the 128 limit.
Batch large generated definitions into chunks under 128.
Prefer the kernel document API for bulk creation.

When it happens

Trigger: Passing a definition list (including all nested children at any depth) whose total document count exceeds 128. Raised from parseTemplateDocTreeDefinition during template insertion.

Common situations: Programmatically generating a large batch of documents (e.g. a year of daily notes = 365 entries); migrating a bulk import through createDocTree; deeply nested definitions that multiply entries.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/76bdf75573550bf3. Report an issue: GitHub.

Appendix: source

Thrown at kernel/model/template_doc_tree.go:177

		if 512 < utf8.RuneCountInString(title) {
			return nil, fmt.Errorf("createDocTree document title exceeds %d characters", 512)
		}

		templateName, err := templateDocTreeStringField(definition, "template")
		if nil != err {
			return nil, err
		}
		defineName, err := templateDocTreeStringField(definition, "define")
		if nil != err {
			return nil, err
		}
		if "" != templateName && "" != defineName {
			return nil, errors.New("createDocTree document template and define are mutually exclusive")
		}

		state.count++
		if maxTemplateDocTreeDocs < state.count {
			return nil, fmt.Errorf("createDocTree exceeds the maximum document count of %d", maxTemplateDocTreeDocs)
		}
		id := ast.NewNodeID()
		node := &TemplateDocTreeNode{
			ID:       id,
			RootID:   id,
			Title:    title,
			Depth:    depth,
			Template: templateName,
			Define:   defineName,
		}
		if childrenValue, exists := definition["children"]; exists {
			children, parseErr := state.parseNodes(childrenValue, depth+1)
			if nil != parseErr {
				return nil, parseErr
			}
			node.Children = children
		}
		nodes = append(nodes, node)

View on GitHub (pinned to 9f775e8a12)