siyuan-note/siyuan · error

builtin color index [%d] must be between %d and %d

Error message

builtin color index [%d] must be between %d and %d

What it means

Builtin palette colors occupy fixed indexes from minBuiltinColorIndex through neutralAVColorIndex (the neutral color). SetWorkspaceAVPalette validates each patch's Index against this closed range and rejects out-of-range patches with this formatted error, preventing updates to undefined palette slots.

Source

Thrown at kernel/model/inline_style.go:194

	inlineStylesLock.Lock()
	defer inlineStylesLock.Unlock()

	if update == nil {
		return nil, false, errors.New("workspace attribute view palette update must not be null")
	}
	current, err := loadInlineStyles()
	if err != nil {
		return nil, false, err
	}
	currentAV := current.AV
	current.AV = &InlineStyleAV{Colors: update.Colors, Order: update.Order}
	updatedIndexes := map[int]struct{}{}
	for _, patch := range update.BuiltinColors {
		if patch == nil {
			return nil, false, errors.New("workspace attribute view builtin color update must not be null")
		}
		if patch.Index < minBuiltinColorIndex || neutralAVColorIndex < patch.Index {
			return nil, false, fmt.Errorf("builtin color index [%d] must be between %d and %d", patch.Index,
				minBuiltinColorIndex, neutralAVColorIndex)
		}
		if _, duplicated := updatedIndexes[patch.Index]; duplicated {
			return nil, false, fmt.Errorf("duplicate workspace attribute view builtin color update [%d]", patch.Index)
		}
		updatedIndexes[patch.Index] = struct{}{}
		filtered := current.Builtin.Colors[:0]
		for _, color := range current.Builtin.Colors {
			if color.Index != patch.Index {
				filtered = append(filtered, color)
			}
		}
		current.Builtin.Colors = filtered
		if patch.Customized {
			current.Builtin.Colors = append(current.Builtin.Colors, &InlineStyleBuiltinColor{
				Index: patch.Index,
				Light: patch.Light,
				Dark:  patch.Dark,

View on GitHub (pinned to 8641553a1f)

Solutions

  1. Clamp/validate patch.Index against minBuiltinColorIndex..neutralAVColorIndex before sending the update
  2. Align index origin with the kernel constant (check minBuiltinColorIndex and neutralAVColorIndex values in inline_style.go)
  3. Re-fetch the current palette (GetInlineStyles / loadInlineStyles output) and only patch known indexes

Example fix

// before: 1-based UI index sent to 0-based kernel
idx := 5 // UI slot 6
update.BuiltinColors = append(update.BuiltinColors,
	&model.InlineStyleBuiltinColorPatch{Index: idx, Color: c})
// after: convert and validate
idx := 5 - 1
if idx < model.MinBuiltinColorIndex || idx > model.NeutralAVColorIndex {
	return fmt.Errorf("color index %d out of range", idx)
}
update.BuiltinColors = append(update.BuiltinColors,
	&model.InlineStyleBuiltinColorPatch{Index: idx, Color: c})
Defensive patterns

Strategy: validation

Validate before calling

if p.Index < model.MinBuiltinColorIndex || p.Index > model.NeutralAVColorIndex {
	return fmt.Errorf("index %d outside [%d,%d]", p.Index, model.MinBuiltinColorIndex, model.NeutralAVColorIndex)
}

Try / catch

_, _, err := model.SetWorkspaceAVPalette(update)
if err != nil && strings.Contains(err.Error(), "must be between") {
	// clamp/recompute the index and retry
}

Prevention

When it happens

Trigger: Submitting a WorkspaceAVPaletteUpdate whose BuiltinColors patch has Index < minBuiltinColorIndex or Index > neutralAVColorIndex, e.g. a plugin computing indexes from 0 or from 1-based UI positions inconsistently.

Common situations: Off-by-one when the UI numbers colors from 1 while the kernel is 0-based (or vice versa); a plugin hard-codes an index beyond the palette size after the palette definition changed; deserialized JSON with a stale index from an older version.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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