siyuan-note/siyuan · error

the document spec is too new

Error message

the document spec is too new

What it means

ErrSpecTooNew is a sentinel error returned when a .sy document's Spec field is greater than the kernel's CurrentSpec, meaning the file was written by a newer SiYuan version with node/attribute formats this kernel cannot safely parse. Parsing is refused to avoid unknown nodes being tolerance-parsed and overwriting the original content.

Solutions

1. Upgrade SiYuan to a version whose CurrentSpec is >= the document's spec
2. Do not open this data directory with the older version; copy data back to the newer installation
3. Exclude/move the too-new documents from the workspace if you must stay on the old version (risk of data loss)
4. Check kernel logs for the logged spec numbers to confirm the version mismatch

Example fix

// before: downgraded kernel sees Spec "4" > CurrentSpec "2"
// after: run a kernel with matching CurrentSpec
var CurrentSpec = "4" // must be >= document Spec
if err := treenode.CheckSpecJSON(data); errors.Is(err, treenode.ErrSpecTooNew) { upgrade() }

// Check spec before opening the data dir
const spec = parseInt(JSON.parse(syFile).Root.Spec, 10);
if (spec > CURRENT_SPEC) { upgradeRequired = true; }

if errors.Is(err, treenode.ErrSpecTooNew) {
  return localizedMsg(model.Conf.Language(275)) // prompt user to upgrade
}

When it happens

Trigger: Opening, rendering an attribute view, or fetching a block (CheckSpec / renderAttrView / setGetBlockInfoError paths) from a workspace whose documents were written by a newer SiYuan version; downgrading the app while keeping the same data directory.

Common situations: User rolled back from a newer release/beta to an older stable; sync brought documents created by a newer client into an older one; opening a newer mobile-created doc on an old desktop version.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• unsupported AI editor actions version
• unsupported attribute view rich text spec
• unsupported box document metadata spec
• unsupported view state version
• encrypted notebook snapshot document is plaintext

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

Appendix: source

Thrown at kernel/treenode/tree.go:152

	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)
}

const BaseSpec = "2"

var CurrentSpec = "4"

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

// CheckSpecJSON 在解析节点之前检查文档规范，避免未知节点被容错解析后覆盖原始内容。
func CheckSpecJSON(data []byte) error {
	var root struct {
		Spec string
	}
	if err := json.Unmarshal(data, &root); nil != err {
		return err
	}
	if err := CheckSpec(&parse.Tree{Root: &ast.Node{Spec: root.Spec}}); nil != err {
		return err
	}
	return checkTableCellRichJSON(data, root.Spec)
}

func CheckSpec(tree *parse.Tree) (err error) {
	if err = ValidateTableCellRich(tree.Root); nil != err {
		return

View on GitHub (pinned to 9f775e8a12)