juicedata/juicefs · error
Mkdir %s: %s
Error message
Mkdir %s: %s
What it means
This error wraps a syscall.Errno returned by jfs.Mkdir() during the `juicefs mdtest` benchmark tool. createDir recursively builds a directory tree (mdtest_tree.N) under the test root, and any metadata-engine failure to create a directory (EEXIST, EACCES, ENOENT, ENOSPC, metadata backend connection loss, etc.) is reported as `Mkdir <path>: <errno>`. It is a pass-through of the meta engine's errno, not a JuiceFS-specific failure.
Source
Thrown at cmd/mdtest.go:52
"github.com/juicedata/juicefs/pkg/vfs"
"github.com/mattn/go-isatty"
"github.com/urfave/cli/v2"
)
var ctx = meta.NewContext(1, uint32(utils.GetCurrentUID()), []uint32{uint32(utils.GetCurrentGID())})
var umask = uint16(utils.GetUmask())
func init() {
// For all the juicefs command, we treat admin/elevated privilege user as root(0) on Windows
// just like the mount option '-adminasroot' does for the mounted filesystem.
if runtime.GOOS == "windows" && utils.IsWinAdminOrElevatedPrivilege() {
ctx = meta.NewContext(1, 0, []uint32{0})
}
}
func createDir(jfs *fs.FileSystem, root string, d int, width int) error {
if err := jfs.Mkdir(ctx, root, 0777, umask); err != 0 {
return fmt.Errorf("Mkdir %s: %s", root, err)
}
if d > 0 {
for i := 0; i < width; i++ {
dn := path.Join(root, fmt.Sprintf("mdtest_tree.%d", i))
if err := createDir(jfs, dn, d-1, width); err != nil {
return err
}
}
}
return nil
}
func createFile(jfs *fs.FileSystem, bar *utils.Bar, np int, root string, d int, width, files, bytes int) error {
m := jfs.Meta()
for i := 0; i < files; i++ {
fn := path.Join(root, fmt.Sprintf("file.mdtest.%d.%d", np, i))
f, err := jfs.Create(ctx, fn, 0666, umask)
if err != 0 {View on GitHub (pinned to c9a67b23e8)
Solutions
- Delete the previous test tree (or use a fresh PATH) before re-running mdtest, since Mkdir on the existing mdtest_tree dirs fails with EEXIST
- Verify the metadata URL is reachable and credentials are correct: run `juicefs status META-URL` first
- Check filesystem permissions on the target path (who owns it, which uid/gid the client runs as) and use --subdir or chown if needed
- Check the meta engine capacity/quota (disk full for SQLite, maxmemory for Redis) if errors appear partway through tree creation
- Run with a smaller -depth/-dirs to isolate which level of the tree fails, then inspect that path
Example fix
// before $ juicefs mdtest redis://localhost /test1 # fails: Mkdir /test1/test-dir.0-0/mdtest_tree.0: file exists // after $ rm -rf /test1 && juicefs mdtest redis://localhost /test1
Defensive patterns
Strategy: validation
Validate before calling
// check target path state before running mdtest
if _, err := os.Stat(path.Join(rootDir, "test-dir.0-0")); err == nil {
return fmt.Errorf("test tree already exists at %s; clean it or pick another PATH", rootDir)
}
// and verify metadata connectivity
// juicefs status META-URL Try / catch
// go: handle errno from the returned error string wrapper
if err := createDir(jfs, root, depth, width); err != nil {
if errors.Is(err, os.ErrExist) || strings.Contains(err.Error(), "file exists") {
logger.Infof("tree exists, cleaning up")
continue
}
logger.Fatalf("initialize: %s", err)
} Prevention
- Always start mdtest on a fresh or cleaned PATH
- Run `juicefs status META-URL` to verify the metadata engine before benchmarking
- Run the client as a user with write permission on the target directory tree
- Avoid concurrent mdtest runs sharing the same PATH
When it happens
Trigger: `juicefs mdtest META-URL PATH` run where: the test root directory already exists (EEXIST) and was not cleaned from a previous run; the running user lacks permission at the parent (EACCES); the parent path was removed concurrently; the metadata engine (Redis/SQL/TiKV) is unreachable or rejects writes; or a recursive createDir call at depth d hits quota/limit.
Common situations: Re-running mdtest against the same PATH without deleting test-dir.0-0 from the previous run; mounting/pointing at a read-only or subdir-restricted volume; running as a non-root user against a volume whose root is root-owned; Redis/MySQL/etcd credentials wrong so metadata writes fail mid-tree.
Understand the failure class
Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.
Related errors
AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06).
Data as JSON: /api/errors/aaf16f00166ba19c.
Report an issue: GitHub.