siyuan-note/siyuan · error

createDocTree document title exceeds %d characters

Error message

createDocTree document title exceeds %d characters

What it means

Document titles longer than 512 Unicode characters (counted in runes after normalization) are rejected. This cap keeps generated paths within filesystem and UX limits, since the title becomes a path segment of the created document.

Source

Thrown at kernel/model/template_doc_tree.go:160

			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++
		if maxTemplateDocTreeDocs < state.count {
			return nil, fmt.Errorf("createDocTree exceeds the maximum document count of %d", maxTemplateDocTreeDocs)
		}

View on GitHub (pinned to 8641553a1f)

Solutions

1. Shorten the title to 512 or fewer characters (rune-aware truncation, not byte truncation, for CJK text).
2. Truncate programmatically at build time: cut to N runes and append an ellipsis or suffix while staying under the cap.
3. Move long text into the document body/template content and keep only a short summary as the title.
4. Pre-validate utf8.RuneCountInString(title) <= 512 before rendering.

Example fix

// before
{"title": veryLongParagraph} // 800 runes
// after
{"title": truncateRunes(veryLongParagraph, 512)}

func truncateRunes(s string, n int) string {
    r := []rune(s)
    if len(r) <= n { return s }
    return string(r[:n])
}
// apply: def["title"] = truncateRunes(title, 512)

func titleWithinLimit(v any) bool {
    m, ok := v.(map[string]any)
    if !ok { return false }
    t, ok := m["title"].(string)
    return ok && utf8.RuneCountInString(t) <= 512
}

nodes, err := parseTemplateDocTreeDefinition(def)
if err != nil {
    if strings.Contains(err.Error(), "title exceeds") {
        // truncate the reported title to 512 runes and retry
    }
    return err
}

When it happens

Trigger: Calling createDocTree with a document whose title contains 513+ characters, e.g. a whole paragraph pasted as a title or generated titles built from long content.

Common situations: Using the first line of imported content as a title; automated pipelines copying long headings; concatenating fields into a title without truncation.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• createDocTree document title must be a string
• createDocTree document title must not be empty
• 106
• Parse template failed: %s
• parse tree [%s] failed

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