siyuan-note/siyuan · error

boot appearance package is too large

Error message

boot appearance package is too large

What it means

Thrown by validateBootAppearancePackage when the cumulative size of regular files in the package exceeds maxBootAppearanceTotalSize. Prevents oversized boot appearance packages from bloating the workspace.

Source

Thrown at kernel/model/boot_appearance.go:550

			}
			if len(relativePath) > maxBootAppearancePathLength ||
				len(strings.Split(filepath.ToSlash(relativePath), "/")) > maxBootAppearancePathDepth {
				return errors.New("boot appearance path is too deep or long")
			}
		}
		if entry.Type()&os.ModeSymlink != 0 {
			return ErrBootAppearanceAssetForbidden
		}
		if entry.IsDir() {
			return nil
		}
		info, infoErr := entry.Info()
		if infoErr != nil || !info.Mode().IsRegular() {
			return ErrBootAppearanceAssetForbidden
		}
		totalSize += info.Size()
		if totalSize > maxBootAppearanceTotalSize {
			return errors.New("boot appearance package is too large")
		}
		return nil
	})
	return err
}

func validateBootAppearanceResource(pluginDir, appearanceDir, relativePath, expectedType string) (filePath,
	contentType string, err error) {
	if !isSafeBootAppearanceRelativePath(relativePath) {
		err = ErrBootAppearanceAssetForbidden
		return
	}
	filePath = filepath.Join(appearanceDir, filepath.FromSlash(relativePath))
	if err = ensureBootAppearancePathHasNoSymlink(pluginDir, filePath); err != nil {
		err = ErrBootAppearanceAssetForbidden
		return
	}
	info, statErr := os.Stat(filePath)

View on GitHub (pinned to 8641553a1f)

Solutions

1. Compress assets (WebP/optimized PNG, lower resolution) to bring total size under the cap.
2. Remove unused or duplicate files from the package.
3. Trim embedded media (shorter/lower-bitrate video) before repackaging.

const fs = require("fs"), path = require("path");
function pkgSize(dir) { let t = 0; for (const e of fs.readdirSync(dir, {withFileTypes: true})) { const p = path.join(dir, e.name); t += e.isDirectory() ? pkgSize(p) : (e.isFile() ? fs.statSync(p).size : 0); } return t; }
if (pkgSize(pkgDir) > MAX_TOTAL_SIZE) throw new Error("package too large");

try { await installBootAppearance(zipPath); } catch (e) { if (String(e).includes("too large")) { /* compress or trim assets */ } else throw e; }

When it happens

Trigger: Installing a package whose files together exceed the total size cap (e.g. several multi-megabyte background images or videos); the running total crosses the limit during the walk.

Common situations: High-resolution uncompressed backgrounds, embedded videos, or forgotten duplicate assets in the archive.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• too many boot appearance entries
• boot appearance path is too deep or long
• custom emoji file is too large
• marketplace package contains too many files
• marketplace package contains a file that is too large

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