{"record":{"id":"6bffef72ce95538e","repo":"siyuan-note/siyuan","slug":"load-template-document-tree-parent-snapshot-failed","errorCode":null,"errorMessage":"load template document tree parent snapshot failed: %w","messagePattern":"load template document tree parent snapshot failed: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/model/transaction.go","lineNumber":2621,"sourceCode":"\t\tif \"restoreCreatedDoc\" == operation.Action && \"\" != operation.templateDocTreeRootID &&\n\t\t\tnil != operation.Tree && nil != operation.Tree.Root &&\n\t\t\toperation.ID == operation.Tree.Root.ID {\n\t\t\tif existingBox, exists := tx.restoredCreatedDocBoxes[operation.ID]; exists {\n\t\t\t\tif existingBox != operation.Tree.Box {\n\t\t\t\t\ttx.restoredCreatedDocBoxes[operation.ID] = \"\"\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\ttx.restoredCreatedDocBoxes[operation.ID] = operation.Tree.Box\n\t\t\t}\n\t\t}\n\t\tif (\"restoreCreatedDoc\" != operation.Action && \"removeCreatedDoc\" != operation.Action) ||\n\t\t\t\"\" == operation.templateDocTreeRootID || nil == operation.Tree {\n\t\t\tcontinue\n\t\t}\n\t\tif nil == tx.templateDocTreeRootSnapshot {\n\t\t\tsnapshot, loadErr := LoadTreeByBlockID(operation.templateDocTreeRootID)\n\t\t\tif nil != loadErr {\n\t\t\t\treturn fmt.Errorf(\"load template document tree parent snapshot failed: %w\", loadErr)\n\t\t\t}\n\t\t\tif nil == snapshot {\n\t\t\t\treturn errors.New(\"template document tree parent snapshot is invalid\")\n\t\t\t}\n\t\t\tif nil != expectedTemplateDocTreeRoot &&\n\t\t\t\t(expectedTemplateDocTreeRoot.ID != snapshot.ID || expectedTemplateDocTreeRoot.Box != snapshot.Box ||\n\t\t\t\t\texpectedTemplateDocTreeRoot.Path != snapshot.Path || expectedTemplateDocTreeRoot.HPath != snapshot.HPath) {\n\t\t\t\treturn errors.New(\"the document used to render the template has changed\")\n\t\t\t}\n\t\t\ttx.templateDocTreeRootSnapshot = snapshot\n\t\t}\n\t\tif nil == tx.templateDocTreeRootSnapshot || tx.templateDocTreeRootSnapshot.ID != operation.templateDocTreeRootID ||\n\t\t\ttx.templateDocTreeRootSnapshot.Box != operation.Tree.Box {\n\t\t\treturn errors.New(\"template document tree parent snapshot is invalid\")\n\t\t}\n\t}\n\ttx.listItemFoldCandidates = nil\n\ttx.listItemFoldCandidateIDs = map[string]struct{}{}","sourceCodeStart":2603,"sourceCodeEnd":2639,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/8641553a1f07374001902d3ce773285db1292b2d/kernel/model/transaction.go#L2603-L2639","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-open/reload the document and retry the template-based document creation so a fresh parent reference is used","Verify the parent document still exists in the notebook (check its .sy file under data/<box>/.siyuan/) and restore it if deleted","Check kernel logs for the wrapped loadErr (%w) to identify the underlying cause (missing file, lock, corruption) and fix that first","Rebuild the notebook index if LoadTreeByBlockID is failing due to a stale index"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// verify the parent document still resolves before creating from template\nconst exists = await fetchPost('/api/filetree/getDoc', {id: parentRootId});\nif (exists.code !== 0) throw new Error('parent document missing: ' + parentRootId);","typeGuard":null,"tryCatchPattern":"try {\n  await insertTemplateDoc(parentId, tpl);\n} catch (e) {\n  if (String(e.message).startsWith('load template document tree parent snapshot failed')) {\n    await reloadDocTree(); // refresh UI/index state\n    await insertTemplateDoc(parentId, tpl); // retry against fresh state\n  } else { throw e; }\n}","preventionTips":["Do not delete or move the parent document while template-based operations are pending","Keep notebooks indexed and avoid concurrent destructive operations from multiple clients","Read the wrapped cause (%w) in kernel logs to fix the underlying load failure first"],"tags":["transaction","templates","document-tree"],"backgroundTag":"file-read-failed","analyzedSha":"8641553a1f07374001902d3ce773285db1292b2d","analyzedAt":"2026-09-11T16:08:28.414Z","contentChangedAt":"2026-09-11T16:08:28.414Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}