What causes "createDocTree document title is required" in siyuan-note/siyuan?

Add a title field to every document object in the definition.

createDocTree document title is required

Error message

createDocTree document title is required

What it means

Every document object in a createDocTree definition must contain a title field; it is the only mandatory key because it becomes the child document's name/path segment. Missing title causes this error before any document is created.

Source

Thrown at kernel/model/template_doc_tree.go:149

	}

	nodes := make([]*TemplateDocTreeNode, 0, len(values))
	for _, value := range values {
		definition, ok := value.(map[string]any)
		if !ok {
			return nil, errors.New("createDocTree document must be a dictionary")
		}
		for key := range definition {
			switch key {
			case "title", "template", "define", "children":
			default:
				return nil, fmt.Errorf("createDocTree document contains unknown field [%s]", key)
			}
		}

		titleValue, ok := definition["title"]
		if !ok {
			return nil, errors.New("createDocTree document title is required")
		}
		title, ok := titleValue.(string)
		if !ok {
			return nil, errors.New("createDocTree document title must be a string")
		}
		title = normalizeDocTitle(title)
		if "" == title {
			return nil, errors.New("createDocTree document title must not be empty")
		}
		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")

View on GitHub (pinned to 8641553a1f)

Solutions

Add a title field to every document object in the definition.
If the title should come from the template, still supply an explicit title string and let the template content provide the body.
Check any code that builds definitions dynamically to always set title (fall back to a generated name if needed).
Validate with a schema check requiring title:string on each node before rendering.

Example fix

// before
{"template": "meeting.md", "children": [{"define": "daily"}]}
// after
{"title": "Meeting", "template": "meeting.md", "children": [{"title": "Daily", "define": "daily"}]}

Defensive patterns

Strategy: validation

Validate before calling

var walk func(nodes []any) error
walk = func(nodes []any) error {
    for _, v := range nodes {
        m, ok := v.(map[string]any)
        if !ok { continue }
        if _, ok := m["title"]; !ok {
            return errors.New("every document needs a title field")
        }
        if c, ok := m["children"]; ok {
            if cl, ok := c.([]any); ok {
                if err := walk(cl); err != nil { return err }
            }
        }
    }
    return nil
}

Type guard

func hasTitle(v any) bool {
    m, ok := v.(map[string]any)
    if !ok { return false }
    _, ok = m["title"]
    return ok
}

Try / catch

nodes, err := parseTemplateDocTreeDefinition(def)
if err != nil {
    if strings.Contains(err.Error(), "title is required") {
        // add a title (or derive one from the template file name) and retry
    }
    return err
}

Prevention

Treat title as mandatory on every node, even when template or define supplies content.
In generators, always set title with a fallback default name.
Lint definitions for the presence of title on all nodes.

When it happens

Trigger: A document object with only template or define, e.g. {"template": "note.md"}; a children entry that forgot the title key; generated definitions where the title key was dropped by serialization.

Common situations: Authors assuming the template file name is used as the title; destructuring/serialization losing empty or absent keys; LLM-generated templates omitting title on child nodes.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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