siyuan-note/siyuan · error

boot appearance not found

Error message

boot appearance not found

What it means

ErrBootAppearanceNotFound is the sentinel error for boot (splash) appearance selections. When SetBootAppearance or asset resolution receives a provider/appearanceID pair, the kernel validates the package name format and the appearance ID, then verifies the appearance actually exists in the installed plugin directory. Any miss — bad format or nonexistent appearance — is reported as this 'not found' error.

Solutions

  1. Confirm the plugin (provider) is installed in the current workspace and the package name matches exactly
  2. Use an appearance ID matching ^[a-z0-9]+(-[a-z0-9]+)*$ (lowercase, digits, single hyphens)
  3. List available appearances via GetBootAppearances and pick a valid (provider, appearanceID) pair
  4. Reset the selection to default by calling SetBootAppearance with both fields empty

Example fix

// before
_, err := model.SetBootAppearance("My Plugin", "Fancy Theme")
// after
_, err := model.SetBootAppearance("my-plugin", "fancy-theme")
Defensive patterns

Strategy: try-catch

Validate before calling

validID := regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`).MatchString(appearanceID)
providerOK := bazaar.IsValidPackageName(provider)

Type guard

func validSelection(provider, id string) bool {
  return bazaar.IsValidPackageName(provider) && regexp.MustCompile(`^[a-z0-9]+(-[a-z0-9]+)*$`).MatchString(id)
}

Try / catch

if _, err := model.SetBootAppearance(p, id); errors.Is(err, model.ErrBootAppearanceNotFound) {
  // fall back to default or re-list available appearances
}

Prevention

When it happens

Trigger: SetBootAppearance with a provider that fails bazaar.IsValidPackageName or an appearanceID failing isValidBootAppearanceID (kernel/model/boot_appearance.go:225); a syntactically valid pair whose appearance directory cannot be resolved by getBootAppearanceByID (line 229); ResolveBootAppearanceAsset referencing an uninstalled/uninstalled-since plugin.

Common situations: Typo'd plugin package name; appearance ID not lower-kebab-case (e.g. 'My_Theme' or 'theme v2'); plugin uninstalled or upgraded so the referenced appearance ID no longer exists; selecting an appearance from a plugin not installed in the current workspace.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/fcfff84c474dfd90. Report an issue: GitHub.

Appendix: source

Thrown at kernel/model/boot_appearance.go:58

const (
	bootAppearanceSchemaVersion = 1
	bootAppearanceDirName       = "boot-appearances"
	bootAppearanceConfigName    = "boot-appearance.json"
	bootAppearanceManifestName  = "boot.json"

	maxBootAppearanceManifestSize = 200 * 1024
	maxBootAppearanceStyleSize    = 200 * 1024
	maxBootAppearanceImageSize    = 5 * 1024 * 1024
	maxBootAppearanceVideoSize    = 20 * 1024 * 1024
	maxBootAppearanceTotalSize    = 50 * 1024 * 1024
	maxBootAppearanceLayers       = 8
	maxBootAppearanceEntries      = 256
	maxBootAppearancePathDepth    = 16
	maxBootAppearancePathLength   = 512
)

var (
	ErrBootAppearanceNotFound       = errors.New("boot appearance not found")
	ErrBootAppearanceAssetForbidden = errors.New("boot appearance asset forbidden")

	bootAppearanceIDPattern    = regexp.MustCompile(`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
	bootAppearanceColorPattern = regexp.MustCompile(`^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$`)
	bootAppearanceConfLock     sync.RWMutex
)

// BootAppearanceSelection 表示当前工作空间选择的启动页外观。
type BootAppearanceSelection struct {
	SchemaVersion int    `json:"schemaVersion"`
	Provider      string `json:"provider"`
	Appearance    string `json:"appearance"`
}

// BootAppearance 描述已经校验且可安全交给启动页渲染的外观。
type BootAppearance struct {
	Enabled         bool                      `json:"enabled"`
	Provider        string                    `json:"provider,omitempty"`

View on GitHub (pinned to 9f775e8a12)