What causes "clone failed: %v" in juicedata/juicefs?

Read the numeric errno and correlate it with errno meanings (28=ENOSPC/quota, 11=EAGAIN retry, etc.)

clone failed: %v

Error message

clone failed: %v

What it means

After writing the Clone request to the mount's control file, the command reads progress replies from the same pipe. The FUSE daemon responds with a final errno; any non-zero errno (clone aborted inside the daemon) is reported as "clone failed: %v" with the numeric error. This means the request was delivered but the server-side clone operation itself failed.

Source

Thrown at cmd/clone.go:155

	wb.Put8(cmode)
	wb.Put8(uint8(threads))
	f, err := openController(srcMp)
	if err != nil {
		return err
	}
	defer f.Close()
	if _, err = f.Write(wb.Bytes()); err != nil {
		return fmt.Errorf("write message: %s", err)
	}

	progress := utils.NewProgress(false)
	defer progress.Done()
	bar := progress.AddCountBar("Cloning entries", 0)
	if _, errno := readProgress(f, func(count uint64, total uint64) {
		bar.SetTotal(int64(total))
		bar.SetCurrent(int64(count))
	}); errno != 0 {
		return fmt.Errorf("clone failed: %v", errno)
	}
	return nil
}

func findMountpoint(fpath string) (string, error) {
	for p := fpath; p != "/"; p = filepath.Dir(p) {
		inode, err := utils.GetFileInode(p)
		if err != nil {
			return "", fmt.Errorf("get inode of %s: %s", p, err)
		}
		if inode == uint64(meta.RootInode) {
			return p, nil
		}
	}
	return "", fmt.Errorf("%s is not inside JuiceFS", fpath)
}

View on GitHub (pinned to c9a67b23e8)

Solutions

Read the numeric errno and correlate it with errno meanings (28=ENOSPC/quota, 11=EAGAIN retry, etc.)
Check volume quota: `juicefs quota` and raise it or free space before cloning
Verify the metadata engine is healthy and reachable (logs of the mount daemon: `juicefs mount` output / log file)
Reduce --threads and retry to lower metadata contention
Re-run the command after transient backend issues; ensure DST does not exist (delete partial results first)

Example fix

# before
juicefs clone /mnt/jfs/bigdir /mnt/jfs/bigdir-copy  # clone failed: quota exceeded
// after
juicefs quota set /mnt/jfs --capacity 1024000
juicefs clone /mnt/jfs/bigdir /mnt/jfs/bigdir-copy

Defensive patterns

Strategy: retry

Validate before calling

if quotaUsed(root) >= quotaLimit(root) {
    return errors.New("insufficient quota for clone; raise quota or free space")
}

Try / catch

if err := runClone(src, dst); strings.Contains(err.Error(), "clone failed:") {
    if isTransient(err) { time.Sleep(retryDelay); err = runClone(src, dst) } // ensure DST absent first
}

Prevention

Check `juicefs quota` capacity before cloning large trees
Keep the metadata backend (Redis/SQL/TiKV) healthy and monitored
Avoid concurrent clone/delete of the same paths
Start with low --threads and scale up based on backend latency

When it happens

Trigger: The metadata engine rejects or fails the internal clone transaction — e.g. quota exceeded (EDQUOT), metadata backend connection lost, destination vanished mid-clone, internal lock conflicts, or the target name became occupied during the operation.

Common situations: Directory quota hit while cloning a large tree; Redis/SQL/TiKV metadata backend temporarily unreachable or timing out; concurrent operations removed the SRC or created DST concurrently; too many threads (—threads) hammering a slow metadata backend.

Related errors

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