siyuan-note/siyuan · error

load template document tree parent snapshot failed: %w

Error message

load template document tree parent snapshot failed: %w

What it means

During transaction commit, operations that create documents from templates carry a templateDocTreeRootID identifying the parent document tree the template was rendered against. The transaction lazily loads that parent snapshot via LoadTreeByBlockID; if loading fails (I/O error, corrupt .sy, indexing gap), the commit aborts and wraps the underlying load error with this message.

Source

Thrown at kernel/model/transaction.go:2621

		if "restoreCreatedDoc" == operation.Action && "" != operation.templateDocTreeRootID &&
			nil != operation.Tree && nil != operation.Tree.Root &&
			operation.ID == operation.Tree.Root.ID {
			if existingBox, exists := tx.restoredCreatedDocBoxes[operation.ID]; exists {
				if existingBox != operation.Tree.Box {
					tx.restoredCreatedDocBoxes[operation.ID] = ""
				}
			} else {
				tx.restoredCreatedDocBoxes[operation.ID] = operation.Tree.Box
			}
		}
		if ("restoreCreatedDoc" != operation.Action && "removeCreatedDoc" != operation.Action) ||
			"" == operation.templateDocTreeRootID || nil == operation.Tree {
			continue
		}
		if nil == tx.templateDocTreeRootSnapshot {
			snapshot, loadErr := LoadTreeByBlockID(operation.templateDocTreeRootID)
			if nil != loadErr {
				return fmt.Errorf("load template document tree parent snapshot failed: %w", loadErr)
			}
			if nil == snapshot {
				return errors.New("template document tree parent snapshot is invalid")
			}
			if nil != expectedTemplateDocTreeRoot &&
				(expectedTemplateDocTreeRoot.ID != snapshot.ID || expectedTemplateDocTreeRoot.Box != snapshot.Box ||
					expectedTemplateDocTreeRoot.Path != snapshot.Path || expectedTemplateDocTreeRoot.HPath != snapshot.HPath) {
				return errors.New("the document used to render the template has changed")
			}
			tx.templateDocTreeRootSnapshot = snapshot
		}
		if nil == tx.templateDocTreeRootSnapshot || tx.templateDocTreeRootSnapshot.ID != operation.templateDocTreeRootID ||
			tx.templateDocTreeRootSnapshot.Box != operation.Tree.Box {
			return errors.New("template document tree parent snapshot is invalid")
		}
	}
	tx.listItemFoldCandidates = nil
	tx.listItemFoldCandidateIDs = map[string]struct{}{}

View on GitHub (pinned to 8641553a1f)

Solutions

1. Re-open/reload the document and retry the template-based document creation so a fresh parent reference is used
2. Verify the parent document still exists in the notebook (check its .sy file under data/<box>/.siyuan/) and restore it if deleted
3. Check kernel logs for the wrapped loadErr (%w) to identify the underlying cause (missing file, lock, corruption) and fix that first
4. Rebuild the notebook index if LoadTreeByBlockID is failing due to a stale index

// verify the parent document still resolves before creating from template
const exists = await fetchPost('/api/filetree/getDoc', {id: parentRootId});
if (exists.code !== 0) throw new Error('parent document missing: ' + parentRootId);

try {
  await insertTemplateDoc(parentId, tpl);
} catch (e) {
  if (String(e.message).startsWith('load template document tree parent snapshot failed')) {
    await reloadDocTree(); // refresh UI/index state
    await insertTemplateDoc(parentId, tpl); // retry against fresh state
  } else { throw e; }
}

When it happens

Trigger: Committing a transaction containing doRestoreCreatedDoc operations with a templateDocTreeRootID whose tree cannot be loaded by LoadTreeByBlockID — e.g. the parent document was deleted or its .sy file is unreadable while a template-created doc transaction is in flight.

Common situations: The parent document was removed in another client between rendering the template and committing; notebook was closed/re-indexed mid-transaction; disk or filelock error reading the tree; synced change removed the parent concurrently.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• template document tree parent snapshot is invalid
• the document used to render the template has changed
• created doc path [%s] already exists
• new item templates config is nil
• parse json [%s] to tree failed: %w

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