siyuan-note/siyuan · error

ErrBootAppearanceNotFound

ErrBootAppearanceNotFound

Error message

boot appearance not found

What it means

The requested boot appearance (splash-screen appearance from a bazaar provider package) cannot be found or is invalid. SetBootAppearance, ResolveBootAppearanceAsset, getBootAppearanceByID, and validateBootAppearancePackage all funnel to this sentinel. It is returned both when the provider package name or appearance id fails format validation (bazaar.IsValidPackageName / isValidBootAppearanceID) and when the appearance entry cannot actually be resolved on disk.

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 8641553a1f)

Solutions

  1. Verify the provider package is installed and the appearance id exists in its manifest (e.g. list available boot appearances before selecting).
  2. Fix format errors: provider must be a valid bazaar package name and appearanceID must match the lowercase kebab-case pattern.
  3. Reset the selection to default by calling SetBootAppearance("", "") and choose again.
  4. If stale config persists across upgrades, clear the stored boot appearance selection file so loadBootAppearanceSelection falls back to the default.

Example fix

// before
_, err := model.SetBootAppearance("MyTheme", "Dark Splash")
// after
_, err := model.SetBootAppearance("my-theme", "dark-splash")
Defensive patterns

Strategy: try-catch

Validate before calling

const idOk = /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(appearanceID)
const providerOk = provider.length > 0 // plus bazaar package-name rules

Try / catch

sel, err := model.SetBootAppearance(provider, id)
if errors.Is(err, model.ErrBootAppearanceNotFound) {
    sel = model.DefaultBootAppearanceSelection() // fall back
}

Prevention

When it happens

Trigger: Calling SetBootAppearance with a provider that is not a valid bazaar package name or an appearanceID not matching ^[a-z0-9]+(-[a-z0-9]+)*$; requesting an appearance id that is not registered in the provider package (getBootAppearanceByID fails, boot_appearance.go:225-229); resolving assets for an appearance whose package has been uninstalled or whose manifest no longer lists it.

Common situations: Configuration persisted from a previous install points at a since-uninstalled or renamed appearance package; typo in the package name or appearance id; API scripts passing arbitrary strings for provider/appearanceID.

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@8641553a1f (2026-09-11). Data as JSON: /api/errors/e0db287092d57198. Report an issue: GitHub.