siyuan-note/siyuan · error

invalid document sort mode

Error message

invalid document sort mode [%d]

What it means

SetDocSortMode declares how a document's child documents are sorted. Before applying, it validates the requested integer sortMode via IsValidDocSortMode; if the number is not one of the recognized sort mode constants, the kernel rejects it with this error. It is a strict enum check on the raw integer sent by the client.

Solutions

  1. Check the valid sort mode constants in the kernel (IsValidDocSortMode / DocSortMode definitions) and use one of those values
  2. Inspect the actual payload being sent and confirm the client is not sending a string-cast or offset number
  3. If the intent is to clear the declaration, send sortMode: null instead of a numeric sentinel like 0
  4. Update the calling plugin/extension to the constants matching the running kernel version

Example fix

// before
SetDocSortMode(docID, intPtr(99))
// after
const sortModeNameAsc = 3 // valid kernel sort mode constant
SetDocSortMode(docID, intPtr(sortModeNameAsc))
Defensive patterns

Strategy: validation

Validate before calling

function isValidDocSortMode(m) { return Number.isInteger(m) && [0,1,2,3,4,5,6,7].includes(m) }
if (!isValidDocSortMode(sortMode)) throw new Error(`unsupported sort mode ${sortMode}`)

Type guard

const isSortMode = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0

Try / catch

try { await api.setDocSortMode(id, sortMode) } catch (e) { if (String(e).includes("invalid document sort mode")) { /* fall back to inherited mode: send null */ } else throw e }

Prevention

When it happens

Trigger: Calling the SetDocSortMode API (or its HTTP route) with sortMode set to an integer outside the valid document sort mode set, e.g. a stale or hand-crafted value like 99 or a negative number.

Common situations: Frontend/plugin code that caches sort mode constants from an older SiYuan version; manual API scripting where the developer guesses numeric mode values; mode flags shifted between releases so a previously valid number is no longer recognized.

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

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

Appendix: source

Thrown at kernel/model/file.go:2500

	if err = filelock.WriteFile(confPath, data); err != nil {
		logging.LogErrorf("write sort conf [%s] failed: %s", confPath, err)
		return err
	}
	return nil
}

type DocSortModeResult struct {
	Box               string `json:"box"`
	ID                string `json:"id"`
	Path              string `json:"path"`
	SortMode          *int   `json:"sortMode"`
	EffectiveSortMode int    `json:"effectiveSortMode"`
}

// SetDocSortMode 设置文档对子文档列表声明的排序方式，sortMode 为 nil 时恢复继承。
func SetDocSortMode(id string, sortMode *int) (ret *DocSortModeResult, err error) {
	if nil != sortMode && !IsValidDocSortMode(*sortMode) {
		return nil, fmt.Errorf("invalid document sort mode [%d]", *sortMode)
	}

	FlushTxQueue()
	tree, err := LoadTreeByBlockID(id)
	if nil != err {
		return nil, err
	}
	if tree.ID != id || tree.Root.ID != id || ast.NodeDocument != tree.Root.Type || IsBoxDoc(tree.Box, tree.ID) {
		return nil, fmt.Errorf("block [%s] is not a document that can declare a child document sort mode", id)
	}

	value := ""
	if nil != sortMode {
		value = strconv.Itoa(*sortMode)
	}
	if tree.Root.IALAttr(DocSortModeAttr) != value {
		if err = setNodeAttrs(tree.Root, tree, map[string]string{DocSortModeAttr: value}); nil != err {
			return nil, err

View on GitHub (pinned to 9f775e8a12)