{"record":{"id":"d655bbcccc61af05","repo":"siyuan-note/siyuan","slug":"invalid-document-sort-mode-d","errorCode":null,"errorMessage":"invalid document sort mode [%d]","messagePattern":"invalid document sort mode \\[(.+?)\\]","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/model/file.go","lineNumber":2500,"sourceCode":"\tif err = filelock.WriteFile(confPath, data); err != nil {\n\t\tlogging.LogErrorf(\"write sort conf [%s] failed: %s\", confPath, err)\n\t\treturn err\n\t}\n\treturn nil\n}\n\ntype DocSortModeResult struct {\n\tBox               string `json:\"box\"`\n\tID                string `json:\"id\"`\n\tPath              string `json:\"path\"`\n\tSortMode          *int   `json:\"sortMode\"`\n\tEffectiveSortMode int    `json:\"effectiveSortMode\"`\n}\n\n// SetDocSortMode 设置文档对子文档列表声明的排序方式，sortMode 为 nil 时恢复继承。\nfunc SetDocSortMode(id string, sortMode *int) (ret *DocSortModeResult, err error) {\n\tif nil != sortMode && !IsValidDocSortMode(*sortMode) {\n\t\treturn nil, fmt.Errorf(\"invalid document sort mode [%d]\", *sortMode)\n\t}\n\n\tFlushTxQueue()\n\ttree, err := LoadTreeByBlockID(id)\n\tif nil != err {\n\t\treturn nil, err\n\t}\n\tif tree.ID != id || tree.Root.ID != id || ast.NodeDocument != tree.Root.Type || IsBoxDoc(tree.Box, tree.ID) {\n\t\treturn nil, fmt.Errorf(\"block [%s] is not a document that can declare a child document sort mode\", id)\n\t}\n\n\tvalue := \"\"\n\tif nil != sortMode {\n\t\tvalue = strconv.Itoa(*sortMode)\n\t}\n\tif tree.Root.IALAttr(DocSortModeAttr) != value {\n\t\tif err = setNodeAttrs(tree.Root, tree, map[string]string{DocSortModeAttr: value}); nil != err {\n\t\t\treturn nil, err","sourceCodeStart":2482,"sourceCodeEnd":2518,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/9f775e8a12daef8255556097396f9b2739078892/kernel/model/file.go#L2482-L2518","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the valid sort mode constants in the kernel (IsValidDocSortMode / DocSortMode definitions) and use one of those values","Inspect the actual payload being sent and confirm the client is not sending a string-cast or offset number","If the intent is to clear the declaration, send sortMode: null instead of a numeric sentinel like 0","Update the calling plugin/extension to the constants matching the running kernel version"],"exampleFix":"// before\nSetDocSortMode(docID, intPtr(99))\n// after\nconst sortModeNameAsc = 3 // valid kernel sort mode constant\nSetDocSortMode(docID, intPtr(sortModeNameAsc))","handlingStrategy":"validation","validationCode":"function isValidDocSortMode(m) { return Number.isInteger(m) && [0,1,2,3,4,5,6,7].includes(m) }\nif (!isValidDocSortMode(sortMode)) throw new Error(`unsupported sort mode ${sortMode}`)","typeGuard":"const isSortMode = (v) => typeof v === \"number\" && Number.isInteger(v) && v >= 0","tryCatchPattern":"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 }","preventionTips":["Always import sort mode constants from the shared frontend constants file, never inline numbers","Send null to reset to inherited sorting instead of a numeric sentinel","Log the payload when sort mode changes to catch stale constants early"],"tags":["go","kernel","sort-mode","validation"],"backgroundTag":"invalid-enum-value","analyzedSha":"9f775e8a12daef8255556097396f9b2739078892","analyzedAt":"2026-09-19T03:17:15.984Z","contentChangedAt":"2026-09-19T03:17:15.984Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}