siyuan-note/siyuan · error

document version is required

Error message

document version is required

What it means

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.

Solutions

1. Ensure the caller constructs and passes a *DocVersionRef before calling ResolveDocVersionBoxID.
2. In API handlers, validate the request body contains the version reference and return a client-side 400 instead of passing nil down.
3. For older clients, return a clear request-validation error before invoking this function.

Example fix

// before
boxID, err := model.ResolveDocVersionBoxID(ref)
// after
if ref == nil {
    return nil, fmt.Errorf("missing document version reference in request")
}
boxID, err := model.ResolveDocVersionBoxID(ref)

if ref == nil {
    return errors.New("document version reference is required")
}
boxID, err := model.ResolveDocVersionBoxID(ref)

func hasDocVersionRef(ref *model.DocVersionRef) bool { return ref != nil }

boxID, err := model.ResolveDocVersionBoxID(ref)
if err != nil && err.Error() == "document version is required" {
    return fmt.Errorf("client must supply a version reference")
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• AI editor action must not be empty
• block [ ] type is locked: expected , got
• block swap requires two non-document blocks
• Bookmark cannot be empty
• can not remove [ ] caused by it is a reserved file

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

Appendix: source

Thrown at kernel/model/history_diff.go:117

	signature string
}

type docTextSegment struct {
	node       *ast.Node
	start      int
	end        int
	storedRuns []string
	signature  string
}

type docDiffLCSBudget struct {
	remaining int
}

// ResolveDocVersionBoxID 返回文档版本引用中明确记录的加密笔记本 ID。
func ResolveDocVersionBoxID(ref *DocVersionRef) (string, error) {
	if ref == nil {
		return "", errors.New("document version is required")
	}
	switch ref.Type {
	case docVersionCurrent:
		if !ast.IsNodeIDPattern(ref.ID) {
			return "", errors.New("current document ID is invalid")
		}
		blockTree := treenode.GetBlockTree(ref.ID)
		if blockTree == nil {
			return "", ErrTreeNotFound
		}
		if IsEncryptedBox(blockTree.BoxID) {
			return blockTree.BoxID, nil
		}
		return "", nil
	case docVersionHistory:
		absPath, err := validateHistoryPath(ref.Path)
		if err != nil {
			return "", err

View on GitHub (pinned to 9f775e8a12)