What causes "the document spec is too new" in siyuan-note/siyuan?

Upgrade the kernel to a version whose CurrentSpec is >= the document's spec.

the document spec is too new

Error message

the document spec is too new

What it means

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.

Source

Thrown at kernel/treenode/tree.go:145

		newID = ast.NewNodeID()
	}
	ret = &ast.Node{ID: newID, Type: ast.NodeParagraph}
	ret.SetIALAttr("id", newID)
	ret.SetIALAttr("updated", newID[:14])
	return
}

func NewSpanAnchor(id string) (ret *ast.Node) {
	return &ast.Node{Type: ast.NodeInlineHTML, Tokens: []byte("<span id=\"" + id + "\" style=\"display: none;\"></span>")}
}

func ContainOnlyDefaultIAL(tree *parse.Tree) bool {
	return 5 > len(tree.Root.KramdownIAL)
}

var CurrentSpec = "2"

var ErrSpecTooNew = fmt.Errorf("the document spec is too new")

func CheckSpec(tree *parse.Tree) (err error) {
	if CurrentSpec == tree.Root.Spec || "" == tree.Root.Spec {
		return
	}

	spec, err := strconv.Atoi(tree.Root.Spec)
	if nil != err {
		logging.LogErrorf("parse spec [%s] failed: %s", tree.Root.Spec, err)
		return
	}

	currentSpec, _ := strconv.Atoi(CurrentSpec)
	if spec > currentSpec {
		logging.LogErrorf("tree spec [%s] is newer than current spec [%s]", tree.Root.Spec, CurrentSpec)
		return ErrSpecTooNew
	}
	return

View on GitHub (pinned to 251596fc0d)

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.

Example fix

// before
if err := treenode.CheckSpec(tree); err != nil {
    log.Fatal(err) // "the document spec is too new"
}

// after: handle the sentinel explicitly
if errors.Is(err := treenode.CheckSpec(tree); err, treenode.ErrSpecTooNew) {
    return fmt.Errorf("document %s requires a newer SiYuan (spec %s > %s)", path, tree.Root.Spec, treenode.CurrentSpec)
}

Defensive patterns

Strategy: try-catch

Try / catch

if err := treenode.CheckSpec(tree); err != nil {
    if errors.Is(err, treenode.ErrSpecTooNew) {
        // document came from a newer SiYuan; do not attempt UpgradeSpec
        return fmt.Errorf("document spec %s newer than supported %s; upgrade SiYuan", tree.Root.Spec, treenode.CurrentSpec)
    }
    return err
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/443dad305ab6d367. Report an issue: GitHub.