juicedata/juicefs · error · FileExistsError

File exists: {path}

Error message

File exists: {path}

What it means

Raised by JuiceFSFS.makedirs in fsspec when the target path already exists and exist_ok is False. It mirrors os.makedirs semantics: directory creation is refused to avoid silently reusing an existing path; pass exist_ok=True to tolerate it.

Source

Thrown at sdk/python/juicefs/juicefs/spec.py:48

    """
    A JuiceFS file system.
    """
    protocol = "jfs", "juicefs"
    def __init__(self, name, auto_mkdir=False, **kwargs):
        if self._cached:
            return
        super().__init__(**kwargs)
        self.auto_mkdir = auto_mkdir
        self.temppath = kwargs.pop("temppath", "/tmp")
        self.fs = Client(name, **kwargs)

    @property
    def fsid(self):
        return "jfs_" + self.fs.name

    def makedirs(self, path, exist_ok=False, mode=511):
        if self.exists(path) and not exist_ok:
            raise FileExistsError(f"File exists: {path}")
        self.fs.makedirs(self._strip_protocol(path), mode, exist_ok=exist_ok)

    def mkdir(self, path, create_parents=True, mode=0o511):
        if self.exists(path):
            raise FileExistsError(f"File exists: {path}")
        if create_parents:
            self.fs.makedirs(self._strip_protocol(path), mode=mode)
        else:
            self.fs.mkdir(self._strip_protocol(path), mode)

    def rmdir(self, path):
        self.fs.rmdir(self._strip_protocol(path))

    def ls(self, path, detail=False, **kwargs):
        infos = self.fs.listdir(self._strip_protocol(path), detail)
        if not detail:
            return infos
        stats = []

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Pass exist_ok=True: fs.makedirs(path, exist_ok=True)
2. Check fs.exists(path) before calling makedirs
3. Catch FileExistsError and treat it as success if the dir is expected

Example fix

// before
fs.makedirs('/mnt/jfs/checkpoints')
// after
fs.makedirs('/mnt/jfs/checkpoints', exist_ok=True)

if fs.exists(path) and not exist_ok:
    return  # or skip creation

try:
    fs.makedirs(path)
except FileExistsError:
    pass  # idempotent create

When it happens

Trigger: Calling fs.makedirs('/a/b') where the path already exists without exist_ok=True; caching layers racing so exists() returns True; calling makedirs on a path created by a previous run of the script.

Common situations: Idempotent setup scripts re-creating directory trees; concurrent workers both calling makedirs; default mode=511 expectation differences.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• invalid mode: {mode}
• must have exactly one of create/read/write/append mode
• can't have text and binary mode at once
• binary mode doesn't take an encoding argument
• binary mode doesn't take an errors argument

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