{"record":{"id":"98456b855450806e","repo":"siyuan-note/siyuan","slug":"unsupported-hpath-refresh-version-d","errorCode":null,"errorMessage":"unsupported hpath refresh version %d","messagePattern":"unsupported hpath refresh version (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/model/hpath_refresh.go","lineNumber":94,"sourceCode":"\nfunc readHPathRefreshTasks(p string) (map[string]*hpathRefreshTask, error) {\n\ttasks := map[string]*hpathRefreshTask{}\n\tdata, err := os.ReadFile(p)\n\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 {","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/9f775e8a12daef8255556097396f9b2739078892/kernel/model/hpath_refresh.go#L76-L112","documentation":"The persisted hpath refresh task store has a version field; readHPathRefreshTasks only understands version 1. When the JSON store on disk was written with a different (newer or corrupt) version number, the loader fails closed instead of misinterpreting an unknown format.","triggerScenarios":"loadHPathRefreshLocked reads the hpath refresh store file whose \"version\" field is not 1 — typically after a downgrade from a newer kernel version that wrote a later format, or manual/manual-tool edits of the store.","commonSituations":"Running an older SiYuan kernel against a workspace written by a newer version; a corrupted store file where the version integer was clobbered; hand-edited store JSON.","solutions":["Upgrade the kernel to the version that wrote the store (check the store's version value against the supported format)","If the store is corrupt or disposable, delete the hpath refresh store file and let the kernel rebuild pending refresh tasks from the document tree","Do not hand-edit the version field to 1 without validating the tasks — entries are re-validated after the version check"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const raw = JSON.parse(storeFile); if (raw && raw.version !== 1) { /* upgrade kernel or drop the store */ }","typeGuard":null,"tryCatchPattern":"tasks, err := model.LoadHPathRefresh(); if err != nil && strings.Contains(err.Error(), \"unsupported hpath refresh version\") { // delete store file or upgrade binary }","preventionTips":["Avoid downgrading the kernel on an active workspace","Never hand-edit internal store JSON files","Back up the workspace before version changes"],"tags":["versioning","persistence","schema","hpath"],"backgroundTag":"unsupported-config-value","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"}