{"record":{"id":"fa13efa7f8cadde5","repo":"siyuan-note/siyuan","slug":"document-version-is-required","errorCode":null,"errorMessage":"document version is required","messagePattern":"document version is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/model/history_diff.go","lineNumber":117,"sourceCode":"\tsignature string\n}\n\ntype docTextSegment struct {\n\tnode       *ast.Node\n\tstart      int\n\tend        int\n\tstoredRuns []string\n\tsignature  string\n}\n\ntype docDiffLCSBudget struct {\n\tremaining int\n}\n\n// ResolveDocVersionBoxID 返回文档版本引用中明确记录的加密笔记本 ID。\nfunc ResolveDocVersionBoxID(ref *DocVersionRef) (string, error) {\n\tif ref == nil {\n\t\treturn \"\", errors.New(\"document version is required\")\n\t}\n\tswitch ref.Type {\n\tcase docVersionCurrent:\n\t\tif !ast.IsNodeIDPattern(ref.ID) {\n\t\t\treturn \"\", errors.New(\"current document ID is invalid\")\n\t\t}\n\t\tblockTree := treenode.GetBlockTree(ref.ID)\n\t\tif blockTree == nil {\n\t\t\treturn \"\", ErrTreeNotFound\n\t\t}\n\t\tif IsEncryptedBox(blockTree.BoxID) {\n\t\t\treturn blockTree.BoxID, nil\n\t\t}\n\t\treturn \"\", nil\n\tcase docVersionHistory:\n\t\tabsPath, err := validateHistoryPath(ref.Path)\n\t\tif err != nil {\n\t\t\treturn \"\", err","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/9f775e8a12daef8255556097396f9b2739078892/kernel/model/history_diff.go#L99-L135","documentation":"ResolveDocVersionBoxID returns the encrypted-notebook box ID recorded in a document version reference. Before inspecting the reference, it rejects a nil *DocVersionRef with this sentinel error: the caller passed no version reference at all, so there is nothing to resolve.","triggerScenarios":"Any API handler / anonymous caller invokes ResolveDocVersionBoxID(nil) - typically when the HTTP request omitted the version-ref payload and the handler forwarded an empty pointer.","commonSituations":"Frontend or plugin calls the diff/version API without supplying the left/right version reference object; JSON body field missing so it unmarshals to nil; older client versions not populating the new DocVersionRef field.","solutions":["Ensure the caller constructs and passes a *DocVersionRef before calling ResolveDocVersionBoxID.","In API handlers, validate the request body contains the version reference and return a client-side 400 instead of passing nil down.","For older clients, return a clear request-validation error before invoking this function."],"exampleFix":"// before\nboxID, err := model.ResolveDocVersionBoxID(ref)\n// after\nif ref == nil {\n    return nil, fmt.Errorf(\"missing document version reference in request\")\n}\nboxID, err := model.ResolveDocVersionBoxID(ref)","handlingStrategy":"validation","validationCode":"if ref == nil {\n    return errors.New(\"document version reference is required\")\n}\nboxID, err := model.ResolveDocVersionBoxID(ref)","typeGuard":"func hasDocVersionRef(ref *model.DocVersionRef) bool { return ref != nil }","tryCatchPattern":"boxID, err := model.ResolveDocVersionBoxID(ref)\nif err != nil && err.Error() == \"document version is required\" {\n    return fmt.Errorf(\"client must supply a version reference\")\n}","preventionTips":["Always populate the version-ref field in API requests","Reject empty payloads at the handler boundary","Keep client payload shapes in sync with the kernel API"],"tags":["validation","nil-argument","document-history","api"],"backgroundTag":"null-argument","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"}