siyuan-note/siyuan · error

invalid hpath refresh entry

Error message

invalid hpath refresh entry

What it means

Each entry in the persisted hpath refresh task store must carry a non-empty document ID and notebook (box) ID. readHPathRefreshTasks rejects any entry with an empty ID or Box, because such a task can never be resolved to a document.

Solutions

1. Open the store file, find the entry with empty id or box, and remove or correct that entry
2. If multiple entries are invalid or the file is truncated, delete the store file and let the kernel reconstruct tasks from the document tree
3. Back up the workspace data directory before editing any internal store JSON

Example fix

// before (corrupt entry)
{"tasks":[{"id":"","box":"20240101120000-abc"}]}
// after (valid entry)
{"tasks":[{"id":"20240101120000-xyz","box":"20240101120000-abc","path":"/doc.sy"}]}

const ok = store.tasks.every(t => t.id && t.box); if (!ok) { /* repair or delete the store file */ }

function isValidEntry(e) { return typeof e === "object" && e !== null && typeof e.id === "string" && e.id.length > 0 && typeof e.box === "string" && e.box.length > 0; }

if err != nil && err.Error() == "invalid hpath refresh entry" { // remove the offending entry or delete the store and rebuild }

When it happens

Trigger: loadHPathRefreshLocked unmarshals the store JSON and encounters a task entry with "id":"" or "box":"" — e.g. truncated/corrupt store file, hand-edited JSON, or a store written by buggy code.

Common situations: Disk corruption or partial write of the store file; manual editing of the JSON store; a crash during a previous write leaving a zero-valued entry.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• builtin color must not be null
• builtin style must not be null
• Conf.Language(317)
• createDocTree definition must be a list
• createDocTree document list must not be empty

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

Appendix: source

Thrown at kernel/model/hpath_refresh.go:98

	if os.IsNotExist(err) {
		return tasks, nil
	}
	if err != nil {
		return nil, err
	}
	var store struct {
		Version int                 `json:"version"`
		Tasks   []hpathRefreshEntry `json:"tasks"`
	}
	if err = json.Unmarshal(data, &store); err != nil {
		return nil, err
	}
	if store.Version != 1 {
		return nil, fmt.Errorf("unsupported hpath refresh version %d", store.Version)
	}
	for _, entry := range store.Tasks {
		if entry.ID == "" || entry.Box == "" {
			return nil, errors.New("invalid hpath refresh entry")
		}
		if _, err = filesys.ValidateBoxRelativePath(entry.Box, entry.Path); err != nil {
			return nil, err
		}
		tasks[entry.Box+"/"+entry.ID] = &hpathRefreshTask{hpathRefreshEntry: entry, recover: true, limit: 256}
	}
	return tasks, nil
}

func saveHPathRefreshLocked() error {
	return writeHPathRefreshTasks(hpathRefresh.file, hpathRefresh.tasks)
}

func writeHPathRefreshTasks(p string, tasks map[string]*hpathRefreshTask) error {
	if len(tasks) == 0 {
		if err := os.Remove(p); err != nil && !os.IsNotExist(err) {
			return err
		}

View on GitHub (pinned to 9f775e8a12)