{"record":{"id":"3ec58dd5f21cec54","repo":"siyuan-note/siyuan","slug":"incompatible-encrypted-index","errorCode":null,"errorMessage":"incompatible encrypted index","messagePattern":"incompatible encrypted index","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/util/encrypted_index.go","lineNumber":62,"sourceCode":"\t\tif _, err = db.Exec(\"CREATE TABLE encrypted_index_meta (kind TEXT NOT NULL, schema_version INTEGER NOT NULL, cipher_settings TEXT NOT NULL)\"); err != nil {\n\t\t\treturn err\n\t\t}\n\t\t_, err = db.Exec(\"INSERT INTO encrypted_index_meta VALUES (?, ?, ?)\", kind, schema, string(encoded))\n\t\treturn err\n\t}\n\tvar storedKind, storedSettings string\n\tvar storedSchema, rows int\n\tif err = db.QueryRow(\"SELECT count(*) FROM encrypted_index_meta\").Scan(&rows); err != nil {\n\t\treturn err\n\t}\n\tif rows != 1 {\n\t\treturn errors.New(\"invalid encrypted index compatibility metadata\")\n\t}\n\tif err = db.QueryRow(\"SELECT kind, schema_version, cipher_settings FROM encrypted_index_meta\").Scan(&storedKind, &storedSchema, &storedSettings); err != nil {\n\t\treturn err\n\t}\n\tif storedKind != kind || storedSchema != schema || storedSettings != string(encoded) {\n\t\treturn errors.New(\"incompatible encrypted index\")\n\t}\n\treturn nil\n}\n","sourceCodeStart":44,"sourceCodeEnd":66,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/8641553a1f07374001902d3ce773285db1292b2d/kernel/util/encrypted_index.go#L44-L66","documentation":"This is the deliberate compatibility gate. The stored metadata row's kind, schema_version, and cipher_settings fingerprint are compared against the values the current build computes; any mismatch means the index was produced by a different format version or different SQLCipher parameters (page size, KDF iterations, HMAC algorithm), and the library refuses to open or rewrite it, preserving the original data rather than risking misinterpretation.","triggerScenarios":"Opening an encrypted index created with a different cipher configuration (e.g. different cipher_page_size/kdf_iter) or a different schema_version/kind than the running kernel expects — returned after CheckEncryptedIndexCompatibility reads the single metadata row.","commonSituations":"Rolling back to an older SiYuan version after the index schema advanced; changing SQLCipher defaults between releases; restoring an index file into a workspace configured with different encryption parameters.","solutions":["Use the kernel version recorded in the index's schema_version — check the release notes / docs/ENCRYPTED-NOTEBOOK.md for the compatible version and run that first so it can migrate","Do not edit encrypted_index_meta or regenerate cipher salts to force a match; instead rebuild the derived index from the source documents, which are unaffected","If a deliberate cipher-parameter change is required, follow the documented format-version migration, which authenticates the source and preserves recovery material"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"var stored string\nif err := db.QueryRow(\"SELECT cipher_settings FROM encrypted_index_meta\").Scan(&stored); err == nil {\n    log.Printf(\"index built with settings: %s\", stored)\n}","typeGuard":null,"tryCatchPattern":"if err := CheckEncryptedIndexCompatibility(db, kind, schema); err != nil {\n    if strings.Contains(err.Error(), \"incompatible encrypted index\") {\n        return fmt.Errorf(\"open with the creating kernel version or rebuild the index; err: %w\", err)\n    }\n    return err\n}","preventionTips":["Read docs/ENCRYPTED-NOTEBOOK.md before changing cipher parameters or upgrading across format versions","Never edit encrypted_index_meta or regenerate salts to force compatibility","Pin the kernel version matching your workspace's index format"],"tags":["sqlite","sqlcipher","versioning","compatibility"],"backgroundTag":"schema-version-mismatch","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"}