siyuan-note/siyuan · error

hidden builtin %s index [%d] must be between %d and %d

Error message

hidden builtin %s index [%d] must be between %d and %d

What it means

Hidden built-in inline styles are referenced by numeric color-index values. Each index must fall within the allowed range: the generic built-in range is [minBuiltinColorIndex, maxBuiltinColorIndex], but when the field is "av" (attribute view) the upper bound is tightened to neutralAVColorIndex. Any out-of-range index in the hidden list aborts normalization.

Source

Thrown at kernel/model/inline_style.go:821

	if !lightColor && !lightBackground {
		return nil, nil, fmt.Errorf("%s must define color or backgroundColor", description)
	}
	if lightColor != darkColor || lightBackground != darkBackground {
		return nil, nil, fmt.Errorf("%s must use the same fields in light and dark themes", description)
	}
	return normalizedLight, normalizedDark, nil
}

func normalizeHiddenBuiltinColorIndexes(indexes []int, field string) (ret []int, err error) {
	ret = make([]int, 0, len(indexes))
	seen := make(map[int]struct{}, len(indexes))
	maxIndex := maxBuiltinColorIndex
	if field == "av" {
		maxIndex = neutralAVColorIndex
	}
	for _, index := range indexes {
		if index < minBuiltinColorIndex || maxIndex < index {
			return nil, fmt.Errorf("hidden builtin %s index [%d] must be between %d and %d", field, index,
				minBuiltinColorIndex, maxIndex)
		}
		if _, exists := seen[index]; exists {
			continue
		}
		seen[index] = struct{}{}
		ret = append(ret, index)
	}
	sort.Ints(ret)
	return ret, nil
}

func normalizeHiddenBuiltinStyleIDs(ids []string) (ret []string, err error) {
	seen := make(map[string]struct{}, len(ids))
	for _, value := range ids {
		id := strings.TrimSpace(value)
		if _, valid := builtinStyleOrder[id]; !valid {
			return nil, fmt.Errorf("invalid hidden builtin style ID [%s]", id)

View on GitHub (pinned to 8641553a1f)

Solutions

  1. Clamp or validate each index to [minBuiltinColorIndex, maxBuiltinColorIndex] before saving (for "av", to neutralAVColorIndex).
  2. Filter the incoming list against the current builtin color table so stale indexes from older versions are dropped instead of failing the save.
  3. Check the config file for typos in the hidden-index arrays.

Example fix

// before
indexes := []int{-1, 3, 99}
conf.HiddenColorIndexes = indexes
// after
indexes := []int{-1, 3, 99}
valid := []int{}
for _, i := range indexes {
  if i >= minBuiltinColorIndex && i <= maxBuiltinColorIndex {
    valid = append(valid, i)
  }
}
conf.HiddenColorIndexes = valid
Defensive patterns

Strategy: validation

Validate before calling

function isValidHiddenIndex(i, isAV) {
  return Number.isInteger(i) && i >= 0 && i <= (isAV ? 9 : 25); // bounds per builtin color table
}

Prevention

When it happens

Trigger: Saving a hidden builtin style/color configuration (normalizeHiddenBuiltinColorIndexes in kernel/model/inline_style.go) with a negative index, an index above maxBuiltinColorIndex, or any index above neutralAVColorIndex when field == "av".

Common situations: Plugin or script storing raw array positions instead of the documented builtin color indexes; configs copied from an older version whose index space differed; users manually editing conf JSON and typos in the index.

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/089c179d24b1b40c. Report an issue: GitHub.