{"record":{"id":"5ada6aeb63c0be37","repo":"juicedata/juicefs","slug":"failed-to-get-startts-which-is-required-for-tikv","errorCode":null,"errorMessage":"failed to get startTS, which is required for TiKV to ensure consistency","messagePattern":"failed to get startTS, which is required for TiKV to ensure consistency","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/tkv_bak.go","lineNumber":54,"sourceCode":"\tkvDumpBatchSize = 10000\n)\n\nfunc (m *kvMeta) dump(ctx Context, opt *DumpOption, ch chan<- *dumpedResult) error {\n\tvar dumps = []func(ctx Context, opt *DumpOption, ch chan<- *dumpedResult) error{\n\t\tm.dumpFormat,\n\t\tm.dumpCounters,\n\t\tm.dumpMix, // node, edge, chunk, symlink, xattr, parent\n\t\tm.dumpSustained,\n\t\tm.dumpDelFiles,\n\t\tm.dumpSliceRef,\n\t\tm.dumpACL,\n\t\tm.dumpQuota,\n\t\tm.dumpDirStat,\n\t\tm.dumpChangeLog,\n\t}\n\tts := m.client.config(\"startTS\")\n\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}","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/tkv_bak.go#L36-L72","documentation":"Consistent dumps from TiKV require a startTS snapshot timestamp; the kvMeta dump path reads the startTS from the TiKV client config and fails if it is absent. Without startTS the dump would not be a consistent point-in-time view, so the tool refuses to proceed.","triggerScenarios":"Running juicefs dump against a TiKV metadata engine when the client configuration does not expose a startTS value (m.client.config(\"startTS\") returns nil) — e.g. unsupported/older TiKV client library, or a build/tag where the TiKV driver does not provide snapshot timestamps.","commonSituations":"Dumping a TiKV-backed volume with an outdated or minimal juicefs build whose TiKV driver lacks startTS support; misconfigured TiKV client that fails to negotiate a snapshot; using the kv driver path instead of the tikv driver.","solutions":["Upgrade JuiceFS to a version whose TiKV driver supplies startTS in client config, then retry the dump.","Ensure the metadata URL uses the tikv:// scheme so the full-featured TiKV driver (not a generic KV driver) is used.","Verify connectivity to PD/TiKV so the client can obtain a timestamp; fix PD address/network errors first.","As a last resort use a metadata-engine-native backup (TiKV's own backup tooling) and check consistency separately."],"exampleFix":"// before\njuicefs dump kv://pd-endpoints out.dump\n// after (ensure TiKV driver with snapshot support)\njuicefs dump tikv://pd-endpoints out.dump","handlingStrategy":"fallback","validationCode":"// shell pre-check: ensure tikv scheme and PD reachable\n[[ $META_URL == tikv://* ]] || { echo \"use tikv:// for consistent dump\"; exit 1; }\ncurl -sf http://<pd-host>:2379/pd/api/v1/version >/dev/null || { echo \"PD unreachable\"; exit 1; }","typeGuard":null,"tryCatchPattern":"if _, err := dump(ctx, meta); err != nil {\n    if strings.Contains(err.Error(), \"startTS\") {\n        logger.Warnf(\"TiKV driver lacks snapshot support; upgrade juicefs\")\n    }\n    return err\n}","preventionTips":["Keep the JuiceFS build current when using TiKV metadata.","Use the tikv:// scheme, not generic kv://, for dumps.","Monitor PD connectivity before scheduled backup jobs."],"tags":["tikv","backup","consistency","metadata"],"backgroundTag":"missing-required-config-field","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"}