siyuan-note/siyuan · error

invalid layer position [%s]

Error message

invalid layer position [%s]

What it means

Thrown by loadBootAppearance when a layer's "position" value is not one of the nine accepted keywords. Empty positions default to "center", so the error indicates an explicitly invalid string. Loading the boot appearance package fails entirely.

Source

Thrown at kernel/model/boot_appearance.go:492

			}
		} else if layer.Poster != "" {
			err = errors.New("image layer cannot declare a poster")
			return nil, err
		}
		fit := layer.Fit
		if fit == "" {
			fit = "cover"
		}
		if !isValidBootAppearanceFit(fit) {
			err = fmt.Errorf("invalid layer fit [%s]", fit)
			return nil, err
		}
		position := layer.Position
		if position == "" {
			position = "center"
		}
		if !isValidBootAppearancePosition(position) {
			err = fmt.Errorf("invalid layer position [%s]", position)
			return nil, err
		}
		item := &BootAppearanceLayer{
			ID:       layer.ID,
			Type:     layer.Type,
			Src:      bootAppearanceAssetURL(pkg.Name, appearanceID, layer.Src),
			Fit:      fit,
			Position: position,
		}
		if layer.Poster != "" {
			item.Poster = bootAppearanceAssetURL(pkg.Name, appearanceID, layer.Poster)
		}
		ret.Layers = append(ret.Layers, item)
	}
	return
}

func validateBootAppearancePackage(pluginDir, appearanceDir string) error {

View on GitHub (pinned to 8641553a1f)

Solutions

1. Change the layer's position in the manifest to one of: center, top, right, bottom, left, top-left, top-right, bottom-right, bottom-left (lowercase, hyphenated).
2. Remove the position field to get the default "center".
3. Spell composite positions with a hyphen (top-left), not a space.

Example fix

// before
"position": "top left"
// after
"position": "top-left"

function validLayerPosition(p) { return !p || ["center","top","right","bottom","left","top-left","top-right","bottom-right","bottom-left"].includes(p); }

const isLayerPosition = (v) => typeof v === "string" && ["center","top","right","bottom","left","top-left","top-right","bottom-right","bottom-left"].includes(v);

try { app = await getBootAppearanceByID(id); } catch (e) { if (String(e).includes("invalid layer position")) { /* correct manifest position field */ } else throw e; }

When it happens

Trigger: GetBootAppearances or getBootAppearanceByID reading a manifest whose layer position is e.g. "middle", "top left" (space instead of hyphen), or "Center" (wrong case).

Common situations: Authors writing CSS-style values ("center center", "50% 50%"), using spaces instead of hyphens, or wrong casing in hand-edited manifests.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• invalid layer fit [%s]
• 199
• invalid marketplace package manifest
• provider and appearance must both be empty or non-empty
• too many layers: %d

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