siyuan-note/siyuan · error

createDocTree document contains unknown field

Error message

createDocTree document contains unknown field [%s]

What it means

The createDocTree template action validates each document object in the definition list. Only the fields title, template, define, and children are recognized; any other key causes parseNodes to reject the whole definition. This strict whitelist prevents typos from silently being ignored and producing unintended document trees.

Solutions

1. Rename or remove the unknown field so the document object contains only title, template, define, and children.
2. Check spelling of the intended key (e.g. template not templat, title not tile).
3. Move auxiliary data out of the createDocTree document object into comments or surrounding template text.
4. If a legitimately needed field is rejected, upgrade SiYuan so the field is supported by the parser.

Example fix

// before
{"title": "Doc", "templat": "tpl.md"}
// after
{"title": "Doc", "template": "tpl.md"}

const allowed = ["title", "template", "define", "children"];
function validateFields(doc) {
  return Object.keys(doc).every(k => allowed.includes(k));
}

When it happens

Trigger: Calling the createDocTree template action with a document object containing a misspelled or extra key such as "tile", "templat", "docs", or a metadata key not in the whitelist. Raised from parseTemplateDocTreeDefinition during template rendering with render mode editorInsert.

Common situations: Typos in template .md files when writing a createDocTree call; copying an older template snippet that used a field name from a different API; hand-editing a template and adding notes as extra keys.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• createDocTree document
• createDocTree document
• createDocTree document template and define are mutually…
• createDocTree document title exceeds
• createDocTree document title is required

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

Appendix: source

Thrown at kernel/model/template_doc_tree.go:143

	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")
	}

	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)
		}

View on GitHub (pinned to 9f775e8a12)