unsupported schema version or mismatched appearance ID

Error message

unsupported schema version or mismatched appearance ID

What it means

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.

Source

Thrown at kernel/model/boot_appearance.go:399

	if err = validateBootAppearancePackage(pluginDir, appearanceDir); err != nil {
		return
	}
	manifestPath, _, resolveErr := validateBootAppearanceResource(pluginDir, appearanceDir, bootAppearanceManifestName, "manifest")
	if resolveErr != nil {
		err = resolveErr
		return
	}
	data, readErr := filelock.ReadFile(manifestPath)
	if readErr != nil {
		err = readErr
		return
	}
	manifest := &bootAppearanceManifest{}
	if err = gulu.JSON.UnmarshalJSON(data, manifest); err != nil {
		return
	}
	if manifest.SchemaVersion != bootAppearanceSchemaVersion || manifest.ID != appearanceID {
		err = errors.New("unsupported schema version or mismatched appearance ID")
		return
	}
	if err = validateBootAppearanceDisplayName(manifest.DisplayName); err != nil {
		return
	}
	frontends, frontendErr := normalizeBootAppearanceFrontends(manifest.Frontends, pkg.Frontends)
	if frontendErr != nil {
		err = frontendErr
		return
	}
	if err = validateOptionalBootAppearanceColor(manifest.BackgroundColor); err != nil {
		return
	}
	if len(manifest.Layers) > maxBootAppearanceLayers {
		err = fmt.Errorf("too many layers: %d", len(manifest.Layers))
		return
	}

View on GitHub (pinned to 8641553a1f)

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

Example fix

// before (appearances/cover/manifest.json)
{"id": "default", "schemaVersion": 1, ...}
// after
{"id": "cover", "schemaVersion": <current schema version>, ...}

Defensive patterns

Strategy: validation

Validate before calling

const manifest = JSON.parse(await file.text());
if (manifest.schemaVersion !== SUPPORTED_SCHEMA_VERSION) throw new Error("update plugin manifest schema");
if (manifest.id !== appearanceDirName) throw new Error(`manifest id ${manifest.id} != directory ${appearanceDirName}`);

Try / catch

// kernel callers already reset to default on this error; mirror that:
try {
  appearance = await getBootAppearance(provider, id);
} catch (e) {
  console.warn("invalid boot appearance, falling back to default", e);
  appearance = defaultAppearance;
}

Prevention

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

When it happens

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

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

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/e54a6f9560eeaf3e. Report an issue: GitHub.