juicedata/juicefs · error

scan dir stats

Error message

scan dir stats

What it means

In kvMeta.doInit (pkg/meta/tkv.go:529), when a volume's format is updated to enable DirStats, the code first scans and collects stale dir-stat keys (prefix "U") in a read transaction; a failure of that scan transaction is wrapped as "scan dir stats". This happens during `juicefs format --enable-dirstats` (or mount with format update) on TiKV/etcd/Badger/FDB engines.

Source

Thrown at pkg/meta/tkv.go:529

		err = json.Unmarshal(body, &old)
		if err != nil {
			return fmt.Errorf("json: %s", err)
		}
		if !old.DirStats && format.DirStats {
			// remove dir stats as they are outdated
			var keys [][]byte
			prefix := m.fmtKey("U")
			err := m.client.txn(Background(), func(tx *kvTxn) error {
				tx.scan(prefix, nextKey(prefix), true, func(k, v []byte) bool {
					if len(k) == 9 {
						keys = append(keys, k)
					}
					return true
				})
				return nil
			}, 0)
			if err != nil {
				return errors.Wrap(err, "scan dir stats")
			}
			err = m.txn(Background(), func(tx *kvTxn) error {
				for _, key := range keys {
					tx.delete(key)
				}
				m.genLog(tx, time.Now(), "INIT_ENABLE_DIRSTATS()")
				return nil
			})
			if err != nil {
				return errors.Wrap(err, "delete dir stats")
			}
		}
		if !old.UserGroupQuota && format.UserGroupQuota {
			// remove user group quota as they are outdated
			userPrefix := m.fmtKey("QU")
			groupPrefix := m.fmtKey("QG")
			err := m.txn(Background(), func(tx *kvTxn) error {
				tx.deleteKeys(userPrefix)

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Check connectivity/health of the KV cluster (TiKV PD, etcd endpoints) and retry the format command.
2. Re-run `juicefs format` with the same flags; the operation is only executed when toggling the feature, so a healthy retry completes it.
3. If a specific store keeps failing, inspect its logs (region errors, leader changes) and repair before re-formatting.

// check KV cluster health before formatting
for _, ep := range pdEndpoints {
    if !reachable(ep) { return fmt.Errorf("PD endpoint %s unreachable", ep) }
}

if err := formatVolume(); err != nil {
    if strings.Contains(err.Error(), "scan dir stats") {
        // KV cluster issue; verify TiKV/PD or etcd health and retry
    }
}

When it happens

Trigger: Formatting/re-formatting a KV-engine volume where old.DirStats is false and the new format enables DirStats, and the scan transaction against the KV store fails (network to TiKV/PD, etcd timeouts, store unavailable).

Common situations: Enabling the dirstats feature on a large old volume whose TiKV/etcd cluster is slow or partially unreachable; transient network partition between client and KV store during format.

Related errors

• delete dir stats
• delete user group quota
• update format
• DumpMeta error: %v
• failed to begin transaction

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