juicedata/juicefs · error

not implemented, use kvMeta.LoadMetaV2 instead

Error message

not implemented, use kvMeta.LoadMetaV2 instead

What it means

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.

Source

Thrown at pkg/meta/tkv_bak.go:71

	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")
}

func (m *kvMeta) prepareLoad(ctx Context, opt *LoadOption) error {
	opt.check()

	var exist bool
	err := m.txn(ctx, func(tx *kvTxn) error {
		exist = tx.exist(m.fmtKey())
		return nil
	})
	if err != nil {
		return err
	}
	if exist {
		return fmt.Errorf("database %s://%s is not empty", m.Name(), m.addr)
	}
	return nil
}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Use juicefs load (which dispatches to LoadMetaV2) with the full backup file instead of the legacy V1 loader.
2. Update any custom scripts/tools that invoke the removed incremental load API to the V2 interface.
3. Upgrade/downgrade JuiceFS so the restore command and the metadata engine implementation versions match.

Example fix

// before: legacy V1 incremental restore path
meta.Load(ctx, false, nil) // hits kvMeta.load -> error
// after: standard V2 restore
juicefs load tikv://pd-endpoints backup.dump

if err := loadBackup(ctx, m, r); err != nil {
    if strings.Contains(err.Error(), "LoadMetaV2") {
        return fmt.Errorf("KV engines only support V2 load: use 'juicefs load'")
    }
    return err
}

When it happens

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

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

Related errors

• The entry of the root inode was not found
• database %s is used by volume %s
• load user/group quotas: %w
• only %d records inserted
• invalid dumped meta: missing 'Counters'

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