siyuan-note/siyuan · error

createDocTree document title exceeds

Error message

createDocTree document title exceeds %d characters

What it means

Document titles in createDocTree definitions are capped at 512 Unicode characters (rune count, measured after normalization). parseNodes enforces this to keep document paths and the filesystem/database sane. The error message interpolates the limit value.

Solutions

1. Shorten the title to 512 characters or fewer (rune count, not bytes).
2. Truncate programmatically in the generator with a rune-aware slice.
3. Move long content into the document body/template and keep the title short.

Example fix

// before
{"title": <600-char string>}
// after
const t = longString.slice(0, 512); // rune-aware truncation
{"title": t, "template": "note.md"}

const within512 = (s) => [...s].length <= 512;
docs.forEach(d => { if (!within512(d.title)) d.title = [...d.title].slice(0, 512).join(''); });

When it happens

Trigger: A title longer than 512 characters, e.g. pasted long text used as a document name or an unbounded template variable expanded into the title. Raised from parseTemplateDocTreeDefinition.

Common situations: Pasting an entire paragraph as a title; a generator embedding long content in the title field; localized titles concatenated from several parts.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• createDocTree exceeds the maximum document count of
• attribute view custom colors count exceeds the
• createDocTree document contains unknown field
• createDocTree document
• createDocTree document

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

Appendix: 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 9f775e8a12)