siyuan-note/siyuan · error

createDocTree exceeds the maximum document count of %d

Error message

createDocTree exceeds the maximum document count of %d

What it means

The createDocTree template action declares more than 128 documents (maxTemplateDocTreeDocs) across the whole tree, including all nested children. During parsing of the definition, a running counter increments per document node; once the 129th document is seen, parsing aborts and returns this error instead of creating a plan. It is a hard safety limit to prevent a template from flooding the notebook with documents.

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 8641553a1f)

Solutions

  1. Reduce the number of documents in the createDocTree definition to 128 or fewer (merge children or drop levels).
  2. Split into multiple template insertions, each creating a partial tree under a different parent.
  3. Create documents programmatically via the API (/api/filetree/createDocWithMkDirs) in batches instead of one template.

Example fix

// before
createDocTree(.{"title":"Week " . $i . "","children":[...25 docs...]}) x 10  // 250+ docs
// after
createDocTree with at most 128 total docs, or split across two template inserts
Defensive patterns

Strategy: validation

Validate before calling

function countDocs(def) {
  return def.reduce((n, d) => n + 1 + (Array.isArray(d.children) ? countDocs(d.children) : 0), 0);
}
if (countDocs(definition) > 128) throw new Error("createDocTree definition exceeds 128 documents");

Type guard

const isDocList = (v) => Array.isArray(v) && v.every((d) => d && typeof d === "object");

Try / catch

try {
  await insertTemplateWithDocTree(def);
} catch (e) {
  if (String(e).includes("exceeds the maximum document count")) {
    // split the definition into batches of <= 128 docs
  }
}

Prevention

When it happens

Trigger: Calling createDocTree with a definition array (nested via "children") whose total flattened node count exceeds 128; also hit indirectly by renderTemplateSource when the template's createDocTree calls plus children exceed the cap.

Common situations: Generating a doc tree for a large project/outline (e.g. a 12-month plan with children per week), bulk-importing a sitemap into docs via a template, or looping/generator logic in the template that emits hundreds of docs.

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@8641553a1f (2026-09-11). Data as JSON: /api/errors/76bdf75573550bf3. Report an issue: GitHub.