siyuan-note/siyuan · error

invalid AV history path [%s]

Error message

invalid AV history path [%s]

What it means

RollbackAttributeViewHistory first runs the generic history-path validation, then requires the target to look like an attribute-view (database) definition file: it must end in .json and sit inside a /storage/av/ segment of the history path. Anything else — doc .sy snapshots, asset files, or JSON files outside storage/av — is rejected with this error.

Source

Thrown at kernel/model/history.go:678

	if err != nil {
		return "", fmt.Errorf("invalid notebook history path [%s]", historyPath)
	}
	parts := strings.Split(filepath.ToSlash(rel), "/")
	if len(parts) != 2 || !strings.HasSuffix(parts[0], "-"+HistoryOpDelete) || !ast.IsNodeIDPattern(parts[1]) ||
		!gulu.File.IsDir(historyPath) || !filelock.IsExist(filepath.Join(historyPath, ".siyuan", "conf.json")) {
		return "", fmt.Errorf("invalid notebook history path [%s]", historyPath)
	}
	return parts[1], nil
}

func RollbackAttributeViewHistory(historyPath string) (err error) {
	historyPath, err = validateHistoryPath(historyPath)
	if err != nil {
		return
	}
	// 验证目标文件必须是 AV 定义文件
	if !strings.HasSuffix(historyPath, ".json") || !strings.Contains(filepath.ToSlash(historyPath), "/storage/av/") {
		return fmt.Errorf("invalid AV history path [%s]", historyPath)
	}

	from := historyPath
	// 从路径提取 boxID 判断是否加密笔记本的 AV
	relPath := strings.TrimPrefix(filepath.ToSlash(historyPath), filepath.ToSlash(util.HistoryDir))
	relPath = strings.TrimPrefix(relPath, "/")
	pathParts := strings.SplitN(relPath, "/", 3)
	data, readErr := filelock.ReadFile(from)
	if readErr != nil {
		return readErr
	}
	ciphertext := util.IsCiphertext(data)
	if ciphertext && (len(pathParts) < 3 || !ast.IsNodeIDPattern(pathParts[1]) || !IsEncryptedBox(pathParts[1])) {
		return errors.New("encrypted attribute view history is missing valid notebook context")
	}
	to := filepath.Join(util.DataDir, "storage", "av", filepath.Base(historyPath))
	if len(pathParts) >= 2 && IsEncryptedBox(pathParts[1]) {
		if !ciphertext {

View on GitHub (pinned to 8641553a1f)

Solutions

  1. Pass only history paths containing /storage/av/<avID>.json, as returned by the database-history listing
  2. Use rollbackDocHistory for .sy files and rollbackAssetsHistory for asset files instead
  3. If the AV history file was moved, restore it to the storage/av/ layout of the snapshot before rolling back

Example fix

// before: doc snapshot passed to AV rollback
rollbackAttributeViewHistory("history/20240101120000-update/<boxID>/<docID>.sy")
// after: AV definition snapshot
rollbackAttributeViewHistory("history/20240101120000-update/<boxID>/storage/av/20240101120000-avxxxx.json")
Defensive patterns

Strategy: validation

Validate before calling

function isAvHistoryPath(historyPath) {
  const normalized = historyPath.replace(/\\/g, "/");
  return normalized.endsWith(".json") && normalized.includes("/storage/av/");
}

Type guard

null

Try / catch

try { await rollbackAttributeViewHistory(p); } catch (e) { if (String(e.msg).startsWith("invalid AV history path")) { /* route .sy to rollbackDocHistory, assets to rollbackAssetsHistory */ } else { throw e; } }

Prevention

When it happens

Trigger: Calling rollbackAttributeViewHistory with a document history path (.sy), an asset history file, or a JSON history file not located under <...>/storage/av/ (e.g. a .siyuan conf.json or widget config).

Common situations: Mixing up rollback endpoints for doc vs database history; databases stored in non-default layouts from third-party tooling; passing a database's live file instead of its history snapshot; plugin automation mapping the wrong history item type to this API.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/a03636d5a6bddd15. Report an issue: GitHub.