{"record":{"id":"586a117e170f1c57","repo":"siyuan-note/siyuan","slug":"invalid-hpath-refresh-entry","errorCode":null,"errorMessage":"invalid hpath refresh entry","messagePattern":"invalid hpath refresh entry","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/model/hpath_refresh.go","lineNumber":98,"sourceCode":"\tif os.IsNotExist(err) {\n\t\treturn tasks, nil\n\t}\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tvar store struct {\n\t\tVersion int                 `json:\"version\"`\n\t\tTasks   []hpathRefreshEntry `json:\"tasks\"`\n\t}\n\tif err = json.Unmarshal(data, &store); err != nil {\n\t\treturn nil, err\n\t}\n\tif store.Version != 1 {\n\t\treturn nil, fmt.Errorf(\"unsupported hpath refresh version %d\", store.Version)\n\t}\n\tfor _, entry := range store.Tasks {\n\t\tif entry.ID == \"\" || entry.Box == \"\" {\n\t\t\treturn nil, errors.New(\"invalid hpath refresh entry\")\n\t\t}\n\t\tif _, err = filesys.ValidateBoxRelativePath(entry.Box, entry.Path); err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\ttasks[entry.Box+\"/\"+entry.ID] = &hpathRefreshTask{hpathRefreshEntry: entry, recover: true, limit: 256}\n\t}\n\treturn tasks, nil\n}\n\nfunc saveHPathRefreshLocked() error {\n\treturn writeHPathRefreshTasks(hpathRefresh.file, hpathRefresh.tasks)\n}\n\nfunc writeHPathRefreshTasks(p string, tasks map[string]*hpathRefreshTask) error {\n\tif len(tasks) == 0 {\n\t\tif err := os.Remove(p); err != nil && !os.IsNotExist(err) {\n\t\t\treturn err\n\t\t}","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/9f775e8a12daef8255556097396f9b2739078892/kernel/model/hpath_refresh.go#L80-L116","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Open the store file, find the entry with empty id or box, and remove or correct that entry","If multiple entries are invalid or the file is truncated, delete the store file and let the kernel reconstruct tasks from the document tree","Back up the workspace data directory before editing any internal store JSON"],"exampleFix":"// before (corrupt entry)\n{\"tasks\":[{\"id\":\"\",\"box\":\"20240101120000-abc\"}]}\n// after (valid entry)\n{\"tasks\":[{\"id\":\"20240101120000-xyz\",\"box\":\"20240101120000-abc\",\"path\":\"/doc.sy\"}]}","handlingStrategy":"validation","validationCode":"const ok = store.tasks.every(t => t.id && t.box); if (!ok) { /* repair or delete the store file */ }","typeGuard":"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; }","tryCatchPattern":"if err != nil && err.Error() == \"invalid hpath refresh entry\" { // remove the offending entry or delete the store and rebuild }","preventionTips":["Do not manually edit the hpath refresh store","Ensure the kernel shuts down cleanly so store writes are not truncated","Validate JSON files after restoring from partial backups"],"tags":["validation","persistence","json","hpath"],"backgroundTag":"empty-required-field","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"}