siyuan-note/siyuan · error

createDocTree document contains unknown field [%s]

Error message

createDocTree document contains unknown field [%s]

What it means

createDocTree document objects allow only four fields: title, template, define, children. Any other key (including misspellings like tittle or extraneous metadata such as id or icon) causes the parser to fail with the offending key name. This strict allowlist catches typos that would otherwise be silently ignored.

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

Solutions

  1. Read the offending key from the error message and remove or rename it to one of title, template, define, children.
  2. Fix common misspellings: children (not childs/chidren), title (not tittle/titel).
  3. Move intended metadata (aliases, custom-*) into the rendered template content instead of the tree definition.
  4. Validate the definition against the four-field schema before rendering to catch this in tooling rather than at runtime.

Example fix

// before
{"title": "Doc", "tittle": "Doc", "custom-flag": "1"}
// after
{"title": "Doc"}
Defensive patterns

Strategy: validation

Validate before calling

allowed := map[string]bool{"title": true, "template": true, "define": true, "children": true}
var walk func(nodes []any) error
walk = func(nodes []any) error {
    for _, v := range nodes {
        m, ok := v.(map[string]any)
        if !ok { continue }
        for k := range m {
            if !allowed[k] {
                return fmt.Errorf("unknown field [%s]", k)
            }
        }
        if c, ok := m["children"]; ok {
            if cl, ok := c.([]any); ok {
                if err := walk(cl); err != nil { return err }
            }
        }
    }
    return nil
}

Type guard

var docFields = map[string]bool{"title": true, "template": true, "define": true, "children": true}
func hasOnlyKnownFields(m map[string]any) bool {
    for k := range m {
        if !docFields[k] { return false }
    }
    return true
}

Try / catch

nodes, err := parseTemplateDocTreeDefinition(def)
if err != nil {
    if strings.Contains(err.Error(), "unknown field") {
        // strip or rename the offending key reported in [%s] and retry
    }
    return err
}

Prevention

When it happens

Trigger: A document object containing any key other than title/template/define/children, e.g. {"tittle": "X"}, {"title": "X", "note": "..."}, or copied IAL attributes like custom-* keys pasted into the definition.

Common situations: Typos in field names (titel, chidren); carrying over fields from other SiYuan template syntaxes; LLM-generated templates inventing plausible-sounding fields; merging document IAL metadata into the tree definition.

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

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