failed to get startTS, which is required for TiKV to ensure

Error message

failed to get startTS, which is required for TiKV to ensure consistency

What it means

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.

Source

Thrown at pkg/meta/tkv_bak.go:54

	kvDumpBatchSize = 10000
)

func (m *kvMeta) dump(ctx Context, opt *DumpOption, ch chan<- *dumpedResult) error {
	var dumps = []func(ctx Context, opt *DumpOption, ch chan<- *dumpedResult) error{
		m.dumpFormat,
		m.dumpCounters,
		m.dumpMix, // node, edge, chunk, symlink, xattr, parent
		m.dumpSustained,
		m.dumpDelFiles,
		m.dumpSliceRef,
		m.dumpACL,
		m.dumpQuota,
		m.dumpDirStat,
		m.dumpChangeLog,
	}
	ts := m.client.config("startTS")
	if ts == nil && m.Name() == "tikv" {
		return errors.New("failed to get startTS, which is required for TiKV to ensure consistency")
	}
	if ts != nil {
		logger.Infof("dump kv with startTS: %d", ts.(uint64))
		ctx = ctx.WithValue(txSessionKey{}, ts)
	}

	for _, f := range dumps {
		err := f(ctx, opt, ch)
		if err != nil {
			return err
		}
	}
	return nil
}

func (m *kvMeta) load(ctx Context, typ int, opt *LoadOption, val proto.Message) error {
	return errors.New("not implemented, use kvMeta.LoadMetaV2 instead")
}

View on GitHub (pinned to c9a67b23e8)

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.

Example fix

// before
juicefs dump kv://pd-endpoints out.dump
// after (ensure TiKV driver with snapshot support)
juicefs dump tikv://pd-endpoints out.dump

Defensive patterns

Strategy: fallback

Validate before calling

// shell pre-check: ensure tikv scheme and PD reachable
[[ $META_URL == tikv://* ]] || { echo "use tikv:// for consistent dump"; exit 1; }
curl -sf http://<pd-host>:2379/pd/api/v1/version >/dev/null || { echo "PD unreachable"; exit 1; }

Try / catch

if _, err := dump(ctx, meta); err != nil {
    if strings.Contains(err.Error(), "startTS") {
        logger.Warnf("TiKV driver lacks snapshot support; upgrade juicefs")
    }
    return err
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/5ada6aeb63c0be37. Report an issue: GitHub.