{"record":{"id":"443dad305ab6d367","repo":"siyuan-note/siyuan","slug":"the-document-spec-is-too-new","errorCode":null,"errorMessage":"the document spec is too new","messagePattern":"the document spec is too new","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"kernel/treenode/tree.go","lineNumber":145,"sourceCode":"\t\tnewID = ast.NewNodeID()\n\t}\n\tret = &ast.Node{ID: newID, Type: ast.NodeParagraph}\n\tret.SetIALAttr(\"id\", newID)\n\tret.SetIALAttr(\"updated\", newID[:14])\n\treturn\n}\n\nfunc NewSpanAnchor(id string) (ret *ast.Node) {\n\treturn &ast.Node{Type: ast.NodeInlineHTML, Tokens: []byte(\"<span id=\\\"\" + id + \"\\\" style=\\\"display: none;\\\"></span>\")}\n}\n\nfunc ContainOnlyDefaultIAL(tree *parse.Tree) bool {\n\treturn 5 > len(tree.Root.KramdownIAL)\n}\n\nvar CurrentSpec = \"2\"\n\nvar ErrSpecTooNew = fmt.Errorf(\"the document spec is too new\")\n\nfunc CheckSpec(tree *parse.Tree) (err error) {\n\tif CurrentSpec == tree.Root.Spec || \"\" == tree.Root.Spec {\n\t\treturn\n\t}\n\n\tspec, err := strconv.Atoi(tree.Root.Spec)\n\tif nil != err {\n\t\tlogging.LogErrorf(\"parse spec [%s] failed: %s\", tree.Root.Spec, err)\n\t\treturn\n\t}\n\n\tcurrentSpec, _ := strconv.Atoi(CurrentSpec)\n\tif spec > currentSpec {\n\t\tlogging.LogErrorf(\"tree spec [%s] is newer than current spec [%s]\", tree.Root.Spec, CurrentSpec)\n\t\treturn ErrSpecTooNew\n\t}\n\treturn","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/kernel/treenode/tree.go#L127-L163","documentation":"ErrSpecTooNew in kernel/treenode/tree.go, returned by CheckSpec when a loaded document's tree.Root.Spec is a number greater than CurrentSpec (currently \"2\"). It means the .sy document was written by a newer SiYuan version whose format this kernel cannot safely interpret. Callers in filesys/tree.go and api/block.go check errors.Is(err, treenode.ErrSpecTooNew) to refuse loading.","triggerScenarios":"Loading (reading) a .sy file whose root spec field is higher than this kernel's CurrentSpec. Encountered by filesys tree loading and the block loading API when opening such a document.","commonSituations":"Downgrading SiYuan to an older version after a newer version wrote documents; opening a doc synced from a newer instance; a manually edited .sy file with a bumped spec.","solutions":["Upgrade the kernel to a version whose CurrentSpec is >= the document's spec.","Open the document in the newer SiYuan that produced it and let it remain there until this kernel is upgraded.","Do not manually lower the spec field — the internal format may genuinely differ and silent corruption could result."],"exampleFix":"// before\nif err := treenode.CheckSpec(tree); err != nil {\n    log.Fatal(err) // \"the document spec is too new\"\n}\n\n// after: handle the sentinel explicitly\nif errors.Is(err := treenode.CheckSpec(tree); err, treenode.ErrSpecTooNew) {\n    return fmt.Errorf(\"document %s requires a newer SiYuan (spec %s > %s)\", path, tree.Root.Spec, treenode.CurrentSpec)\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := treenode.CheckSpec(tree); err != nil {\n    if errors.Is(err, treenode.ErrSpecTooNew) {\n        // document came from a newer SiYuan; do not attempt UpgradeSpec\n        return fmt.Errorf(\"document spec %s newer than supported %s; upgrade SiYuan\", tree.Root.Spec, treenode.CurrentSpec)\n    }\n    return err\n}","preventionTips":["Upgrade SiYuan before opening documents created by a newer version.","Detect ErrSpecTooNew with errors.Is and refuse to load rather than guessing the format.","Never manually edit the spec field in a .sy file to force compatibility."],"tags":["spec","version","compatibility","document","upgrade"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}