siyuan-note/siyuan · error

createDocTree document title must not be empty

Error message

createDocTree document title must not be empty

What it means

After normalization (trimming whitespace), a title that becomes the empty string is rejected. A document cannot exist without a name, so parseNodes refuses entries whose title is blank or only whitespace. This fires even when a non-empty string was supplied, because normalization strips it away.

Solutions

  1. Provide a real, non-empty title string for each document entry.
  2. Check that any template variable used in the title resolves to non-empty content before rendering.
  3. Trim/validate titles in the generator so empty values fail early with a clear message.

Example fix

// before
{"title": "   ", "template": "note.md"}
// after
{"title": "Meeting notes", "template": "note.md"}
Defensive patterns

Strategy: validation

Validate before calling

const hasNonEmptyTitle = (d) => typeof d.title === 'string' && d.title.trim() !== '';
if (!docs.every(hasNonEmptyTitle)) throw new Error('all docs need a non-empty title');

Type guard

const hasNonEmptyTitle = (d) => typeof d.title === 'string' && d.title.trim() !== '';

Prevention

When it happens

Trigger: Titles like "", " ", or strings consisting only of characters removed by normalizeDocTitle (e.g. stray control characters) passed in a createDocTree document object.

Common situations: Template variables that expand to empty ({{title}} unresolved); script-built definitions where a lookup returned an empty value; copy-pasted placeholder titles.

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

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

Appendix: source

Thrown at kernel/model/template_doc_tree.go:157

		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")
		if nil != err {
			return nil, err
		}
		if "" != templateName && "" != defineName {
			return nil, errors.New("createDocTree document template and define are mutually exclusive")
		}

		state.count++

View on GitHub (pinned to 9f775e8a12)