{"record":{"id":"7857dc73162f65dc","repo":"juicedata/juicefs","slug":"not-implemented-use-kvmeta-loadmetav2-instead","errorCode":null,"errorMessage":"not implemented, use kvMeta.LoadMetaV2 instead","messagePattern":"not implemented, use kvMeta\\.LoadMetaV2 instead","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/tkv_bak.go","lineNumber":71,"sourceCode":"\tif ts == nil && m.Name() == \"tikv\" {\n\t\treturn errors.New(\"failed to get startTS, which is required for TiKV to ensure consistency\")\n\t}\n\tif ts != nil {\n\t\tlogger.Infof(\"dump kv with startTS: %d\", ts.(uint64))\n\t\tctx = ctx.WithValue(txSessionKey{}, ts)\n\t}\n\n\tfor _, f := range dumps {\n\t\terr := f(ctx, opt, ch)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc (m *kvMeta) load(ctx Context, typ int, opt *LoadOption, val proto.Message) error {\n\treturn errors.New(\"not implemented, use kvMeta.LoadMetaV2 instead\")\n}\n\nfunc (m *kvMeta) prepareLoad(ctx Context, opt *LoadOption) error {\n\topt.check()\n\n\tvar exist bool\n\terr := m.txn(ctx, func(tx *kvTxn) error {\n\t\texist = tx.exist(m.fmtKey())\n\t\treturn nil\n\t})\n\tif err != nil {\n\t\treturn err\n\t}\n\tif exist {\n\t\treturn fmt.Errorf(\"database %s://%s is not empty\", m.Name(), m.addr)\n\t}\n\treturn nil\n}","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/tkv_bak.go#L53-L89","documentation":"The legacy V1 incremental load path (kvMeta.load) is intentionally unimplemented for KV engines; all loading must go through kvMeta.LoadMetaV2. Hitting this means some code path attempted the obsolete per-record load API instead of the V2 bulk loader.","triggerScenarios":"Calling the legacy load path (typ int, val proto.Message) on a KV metadata engine — typically via an old restore code path or a caller that did not dispatch to LoadMetaV2.","commonSituations":"Running an outdated restore routine against a TiKV/etcd/Badger/FDB engine; custom tooling that reuses the removed incremental-load API; version mismatch where a caller assumes V1 semantics.","solutions":["Use juicefs load (which dispatches to LoadMetaV2) with the full backup file instead of the legacy V1 loader.","Update any custom scripts/tools that invoke the removed incremental load API to the V2 interface.","Upgrade/downgrade JuiceFS so the restore command and the metadata engine implementation versions match."],"exampleFix":"// before: legacy V1 incremental restore path\nmeta.Load(ctx, false, nil) // hits kvMeta.load -> error\n// after: standard V2 restore\njuicefs load tikv://pd-endpoints backup.dump","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"if err := loadBackup(ctx, m, r); err != nil {\n    if strings.Contains(err.Error(), \"LoadMetaV2\") {\n        return fmt.Errorf(\"KV engines only support V2 load: use 'juicefs load'\")\n    }\n    return err\n}","preventionTips":["Use the standard juicefs load CLI for KV engines instead of custom restore code.","Remove calls to the deprecated V1 incremental load API.","Keep restore tooling version-aligned with the cluster's client version."],"tags":["metadata","backup-restore","kv","unsupported"],"backgroundTag":"method-not-implemented","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"}