{"record":{"id":"e54a6f9560eeaf3e","repo":"siyuan-note/siyuan","slug":"unsupported-schema-version-or-mismatched-appearanc","errorCode":null,"errorMessage":"unsupported schema version or mismatched appearance ID","messagePattern":"unsupported schema version or mismatched appearance ID","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/model/boot_appearance.go","lineNumber":399,"sourceCode":"\tif err = validateBootAppearancePackage(pluginDir, appearanceDir); err != nil {\n\t\treturn\n\t}\n\tmanifestPath, _, resolveErr := validateBootAppearanceResource(pluginDir, appearanceDir, bootAppearanceManifestName, \"manifest\")\n\tif resolveErr != nil {\n\t\terr = resolveErr\n\t\treturn\n\t}\n\tdata, readErr := filelock.ReadFile(manifestPath)\n\tif readErr != nil {\n\t\terr = readErr\n\t\treturn\n\t}\n\tmanifest := &bootAppearanceManifest{}\n\tif err = gulu.JSON.UnmarshalJSON(data, manifest); err != nil {\n\t\treturn\n\t}\n\tif manifest.SchemaVersion != bootAppearanceSchemaVersion || manifest.ID != appearanceID {\n\t\terr = errors.New(\"unsupported schema version or mismatched appearance ID\")\n\t\treturn\n\t}\n\tif err = validateBootAppearanceDisplayName(manifest.DisplayName); err != nil {\n\t\treturn\n\t}\n\tfrontends, frontendErr := normalizeBootAppearanceFrontends(manifest.Frontends, pkg.Frontends)\n\tif frontendErr != nil {\n\t\terr = frontendErr\n\t\treturn\n\t}\n\tif err = validateOptionalBootAppearanceColor(manifest.BackgroundColor); err != nil {\n\t\treturn\n\t}\n\tif len(manifest.Layers) > maxBootAppearanceLayers {\n\t\terr = fmt.Errorf(\"too many layers: %d\", len(manifest.Layers))\n\t\treturn\n\t}\n","sourceCodeStart":381,"sourceCodeEnd":417,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/8641553a1f07374001902d3ce773285db1292b2d/kernel/model/boot_appearance.go#L381-L417","documentation":"After parsing the appearance manifest.json, loadBootAppearance verifies that manifest.SchemaVersion equals the kernel's supported bootAppearanceSchemaVersion AND that manifest.ID equals the requested appearanceID. Either mismatch aborts the load, so manifests written for a different format version or copied from another appearance are refused.","triggerScenarios":"GetBootAppearances/getBootAppearanceByID loading a manifest.json whose schemaVersion is older or newer than bootAppearanceSchemaVersion, or whose id field does not match the requested appearance ID (directory name passed to loadBootAppearance).","commonSituations":"Plugin written against an older SiYuan boot-appearance format that the kernel no longer accepts; manifest copied as a template but the id field left as the original appearance's ID; directory renamed without updating manifest.id; hand-edited manifest introducing a typo in the id.","solutions":["Set manifest.json's schemaVersion to the version the running kernel expects (check the kernel source constant bootAppearanceSchemaVersion)","Set manifest.json's id field to exactly the appearance directory name being requested","Re-download or update the plugin to a version compatible with the current SiYuan boot-appearance schema","If you renamed the appearance directory, update manifest.json's id in the same change"],"exampleFix":"// before (appearances/cover/manifest.json)\n{\"id\": \"default\", \"schemaVersion\": 1, ...}\n// after\n{\"id\": \"cover\", \"schemaVersion\": <current schema version>, ...}","handlingStrategy":"validation","validationCode":"const manifest = JSON.parse(await file.text());\nif (manifest.schemaVersion !== SUPPORTED_SCHEMA_VERSION) throw new Error(\"update plugin manifest schema\");\nif (manifest.id !== appearanceDirName) throw new Error(`manifest id ${manifest.id} != directory ${appearanceDirName}`);","typeGuard":null,"tryCatchPattern":"// kernel callers already reset to default on this error; mirror that:\ntry {\n  appearance = await getBootAppearance(provider, id);\n} catch (e) {\n  console.warn(\"invalid boot appearance, falling back to default\", e);\n  appearance = defaultAppearance;\n}","preventionTips":["Bump and test schemaVersion whenever the kernel changes the boot-appearance format","Keep manifest id byte-identical to the directory name","Never copy a manifest between appearance folders without editing its id","Pin plugin releases to the kernel schema version they were built for"],"tags":["validation","schema","plugin","version"],"backgroundTag":"schema-validation-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"}