siyuan-note/siyuan · error

createDocTree requires at least one document

Error message

createDocTree requires at least one document

What it means

parseTemplateDocTreeDefinition parses the createDocTree definition block inside a template and requires it to produce at least one document node. If the parsed node list is empty, it fails with this error, preventing creation of a zero-document tree. Callers include the collector's create function and unit tests.

Source

Thrown at kernel/model/template_doc_tree.go:112

	nodes         []*TemplateDocTreeNode
	enabled       bool
	allowCreation bool
	totalOutput   int
}

var (
	templateDocTreePlans     sync.Map
	templateDocTreePlansLock sync.Mutex
)

func parseTemplateDocTreeDefinition(def any) ([]*TemplateDocTreeNode, error) {
	state := &templateDocTreeParseState{}
	nodes, err := state.parseNodes(def, 1)
	if nil != err {
		return nil, err
	}
	if 0 == len(nodes) {
		return nil, errors.New("createDocTree requires at least one document")
	}
	return nodes, nil
}

type templateDocTreeParseState struct {
	count int
}

func (state *templateDocTreeParseState) parseNodes(value any, depth int) ([]*TemplateDocTreeNode, error) {
	if maxTemplateDocTreeDepth < depth {
		return nil, fmt.Errorf("createDocTree exceeds the maximum depth of %d", maxTemplateDocTreeDepth)
	}
	values, ok := value.([]any)
	if !ok {
		return nil, errors.New("createDocTree definition must be a list")
	}
	if 0 == len(values) {
		return nil, errors.New("createDocTree document list must not be empty")

View on GitHub (pinned to 8641553a1f)

Solutions

1. Add at least one document entry to the createDocTree definition block in the template.
2. If the tree is intentionally empty, remove the .action{createDocTree ...} call entirely.
3. Check that document entries are not commented out or misplaced outside the definition block.

Example fix

<!-- before -->
.action{createDocTree ""}
<!-- after -->
.action{createDocTree "doc1"}
- content of doc1

// Ensure the createDocTree definition contains at least one document entry before rendering
if (!/-\s+\S/.test(extractCreateDocTreeBlock(md))) {
  throw new Error("createDocTree definition has no documents");
}

try {
  await renderTemplate(p);
} catch (e) {
  if (String(e).includes("requires at least one document")) {
    console.error("Add a document entry to the createDocTree definition or remove the call");
  }
  throw e;
}

When it happens

Trigger: A template calling .action{createDocTree ...} whose definition block contains no document entries — empty body, only comments/blank lines, or entries that all failed to parse upstream (though those usually return their own error).

Common situations: Manually emptying a createDocTree definition while keeping the call; copy-pasting a template skeleton with the document list removed; template-generation code emitting an empty definition.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• template output exceeds %d bytes
• createDocTree document list must not be empty
• createDocTree document title must not be empty
• Parse template failed: %s
• parse tree [%s] failed

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