siyuan-note/siyuan · error

boot appearance path is too deep or long

Error message

boot appearance path is too deep or long

What it means

Thrown by validateBootAppearancePackage when a package entry's relative path is longer than maxBootAppearancePathLength or nested deeper than maxBootAppearancePathDepth. Bounds both name length and directory nesting for safety.

Source

Thrown at kernel/model/boot_appearance.go:535

	}
	var totalSize int64
	entryCount := 0
	err = filepath.WalkDir(appearanceDir, func(filePath string, entry os.DirEntry, walkErr error) error {
		if walkErr != nil {
			return walkErr
		}
		relativePath, relativeErr := filepath.Rel(appearanceDir, filePath)
		if relativeErr != nil {
			return ErrBootAppearanceAssetForbidden
		}
		if relativePath != "." {
			entryCount++
			if entryCount > maxBootAppearanceEntries {
				return errors.New("too many boot appearance entries")
			}
			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
	})

View on GitHub (pinned to 8641553a1f)

Solutions

1. Flatten the directory structure so assets sit in few shallow directories.
2. Shorten long file/folder names in the package.
3. Repackage the archive so paths are relative and shallow before installing.

Example fix

// before
assets/layers/v2/frames/final/export/background.png
// after
background.png

function pathTooDeep(rel) { const s = rel.replace(/\\/g, "/"); return s.length > 256 || s.split("/").length > 12; }

try { await installBootAppearance(zipPath); } catch (e) { if (String(e).includes("too deep or long")) { /* flatten package paths */ } else throw e; }

When it happens

Trigger: A package containing files under deeply nested directories (e.g. assets/layers/v2/png/frames/final/... ) or with very long file names; detected during the package walk.

Common situations: Re-zipping exported design-tool folders that carry deep internal structure, or archiving tools preserving original absolute-ish paths.

Understand the failure class

Background: Path traversal blocked: "path escapes the workspace" and "outside site root" errors when a path will not stay inside its allowed directory — this error's family across 26 libraries.

Related errors

• too many boot appearance entries
• boot appearance package is too large
• 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/8c34bc58382bd129. Report an issue: GitHub.