siyuan-note/siyuan · error

too many layers: %d

Error message

too many layers: %d

What it means

The manifest declares more layers than maxBootAppearanceLayers allows, so loadBootAppearance refuses to build a BootAppearance with an oversized layer stack. The cap bounds rendering cost and manifest size for the boot screen.

Source

Thrown at kernel/model/boot_appearance.go:414

		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
	}

	ret = &BootAppearance{
		Enabled:         true,
		Provider:        pkg.Name,
		Appearance:      appearanceID,
		DisplayName:     bazaar.GetPreferredLocaleString(bazaar.LocaleStrings(manifest.DisplayName), appearanceID),
		Frontends:       frontends,
		BackgroundColor: manifest.BackgroundColor,
		OfficialUI: &BootAppearanceOfficialUI{
			ShowLogo:    true,
			ShowDetails: true,
		},
	}
	if manifest.OfficialUI.ShowLogo != nil {
		ret.OfficialUI.ShowLogo = *manifest.OfficialUI.ShowLogo
	}

View on GitHub (pinned to 8641553a1f)

Solutions

1. Reduce the layers array in the appearance's manifest.json to at most maxBootAppearanceLayers entries
2. Replace frame-by-frame image layers with a single video layer (mp4) for animations
3. Merge overlapping visual layers into one image using an image editor
4. If the manifest was generated by a tool, regenerate it with the layer cap respected

Example fix

// before (manifest.json layers)
"layers": [{"id":"l1","type":"image","src":"1.png"}, ... 20 more]
// after
"layers": [
  {"id":"bg","type":"image","src":"bg.png"},
  {"id":"anim","type":"video","src":"anim.mp4","poster":"poster.png"}
]

const MAX_LAYERS = 8; // check kernel constant maxBootAppearanceLayers
if (Array.isArray(manifest.layers) && manifest.layers.length > MAX_LAYERS) {
  throw new Error(`manifest has ${manifest.layers.length} layers, max ${MAX_LAYERS}`);
}

When it happens

Trigger: GetBootAppearances/getBootAppearanceByID loading a manifest.json whose layers array length exceeds maxBootAppearanceLayers (kernel constant). Triggered during plugin install scanning, boot-appearance listing, or selection resolution whenever the manifest lists too many image/video layers.

Common situations: Plugin author animates a boot screen by stacking dozens of images instead of using video or CSS; merging layers from two templates produced a manifest with duplicates; auto-generated manifest enumerating every frame of an animation as separate layers.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• invalid or duplicate layer ID
• unsupported layer type [%s]
• video poster is required
• image layer cannot declare a poster
• 199

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