{"record":{"id":"208598fc1b3be2ec","repo":"juicedata/juicefs","slug":"the-entry-of-the-root-inode-was-not-found-208598","errorCode":null,"errorMessage":"The entry of the root inode was not found","messagePattern":"The entry of the root inode was not found","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/meta/tkv.go","lineNumber":4097,"sourceCode":"\t\t}\n\t\tif err = m.dumpEntry(root, tree, nil); err != nil {\n\t\t\treturn err\n\t\t}\n\t\tif root == RootInode && !skipTrash {\n\t\t\ttrash = &DumpedEntry{\n\t\t\t\tAttr: &DumpedAttr{\n\t\t\t\t\tInode: TrashInode,\n\t\t\t\t\tType:  \"directory\",\n\t\t\t\t},\n\t\t\t}\n\t\t\tif err = m.dumpEntry(TrashInode, trash, nil); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t}\n\t}\n\n\tif tree == nil || tree.Attr == nil {\n\t\treturn errors.New(\"The entry of the root inode was not found\")\n\t}\n\ttree.Name = \"FSTree\"\n\n\tvar rs [][]byte\n\terr = m.txn(Background(), func(tx *kvTxn) error {\n\t\trs = tx.gets(m.counterKey(usedSpace),\n\t\t\tm.counterKey(totalInodes),\n\t\t\tm.counterKey(\"nextInode\"),\n\t\t\tm.counterKey(\"nextChunk\"),\n\t\t\tm.counterKey(\"nextSession\"),\n\t\t\tm.counterKey(\"nextTrash\"))\n\t\treturn nil\n\t})\n\tif err != nil {\n\t\treturn err\n\t}\n\tcs := make([]int64, len(rs))\n\tfor i, r := range rs {","sourceCodeStart":4079,"sourceCodeEnd":4115,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/tkv.go#L4079-L4115","documentation":"During kvMeta.Load (V1 dump-format loading) in the TKV metadata engine, the code looks up the entry for root inode 1; if the tree record is missing or has no Attr, it refuses to continue. This means the loaded snapshot is not a valid JuiceFS metadata tree (root inode absent) or the load was given a malformed/empty key-range.","triggerScenarios":"Calling juicefs load (kvMeta.Load) against a backup file that lacks the root inode (inode 1) entry, loading a corrupted or truncated dump, or loading data dumped with an incompatible/older format into a TKV engine (TiKV/etcd/Badger/FoundationDB).","commonSituations":"Restoring a manually edited or partially copied backup; loading a dump produced from a different tool/format; mixing versions where the dump predates fields the loader requires; loading into an empty engine from a file whose tree segment was lost.","solutions":["Verify the backup file is a complete, unmodified juicefs dump that contains the root inode (inode 1) entry; re-dump from the source volume if it was truncated.","Check the dump/load filter options (paths/inode ranges) — ensure the load actually includes the FSTree/root entry instead of a partial subtree.","Confirm dump/load format compatibility between the client versions producing and consuming the backup; upgrade the loading client if the dump is from a newer version.","If the target engine is not empty, check for conflicting partial loads; wipe the target and retry with a verified backup."],"exampleFix":"// before (loading a filtered backup that dropped root)\njuicefs load redis://127.0.0.1:6379/1 partial.dump\n// after (verify root entry exists, then load full backup)\ngrep -m1 '\"inode\":1' full.dump\njuicefs load redis://127.0.0.1:6379/1 full.dump","handlingStrategy":"validation","validationCode":"import \"encoding/json\"\nfunc backupHasRootInode(dump []byte) bool {\n    for _, line := range bytes.Split(dump, []byte(\"\\n\")) {\n        var rec struct{ Inode Ino `json:\"inode\"` }\n        if json.Unmarshal(line, &rec) == nil && rec.Inode == 1 {\n            return true\n        }\n    }\n    return false\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always produce backups with juicefs dump; never hand-edit or partially copy dump files.","Verify a backup restores into a scratch engine before trusting it.","Pin matching client versions for dump and load across mixed-version clusters."],"tags":["metadata","backup-restore","tikv","corruption"],"backgroundTag":"entity-not-found","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}