ErrLookup › Background articles › "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it

"already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it

"File already exists" errors — surfaced as FileAlreadyExistsException, AlreadyExistsException, io::ErrorKind::AlreadyExists, EEXIST, or a plain "already exists" message — happen when a program tries to create, copy, write, or move a file onto a path that is already occupied and was not told it may overwrite. Developers meet this family when re-running jobs against stale output, sharing directories or store locations between two writers, reinstalling tools over existing files, or relying on create-once semantics that hit an existing file. This page explains the layers that produce it, the common causes (stale leftovers, reruns, races, default overwrite=false), and the fixes that hold across libraries.

Distilled from 92 documented records across 37 repositories.

Background

This family lives at the boundary between an application's intent ('put content at this path') and the filesystem's refusal to let an existing entry be silently replaced. At the lowest level it is the POSIX O_CREAT|O_EXCL / EEXIST contract: exclusive creation fails if the target exists. High-level APIs reinterpret that contract in two directions. Hadoop's FileSystem and FileContext stack, and its object-store connectors (OBS, CosN, GCS, TOS), formalize it as an explicit overwrite flag: fs.create(path) defaults overwrite to false, so any create over an existing file throws FileAlreadyExistsException, and creating over a directory throws even with overwrite=true. Deno's fs.cp does the opposite by default — it skips — and only errors with EEXIST / ERR_FS_CP_EEXIST when you set errorOnExist with force:false. Node's copyFile with COPYFILE_EXCL, Rust's create_new, and shells' noclobber (used by mastra's sandbox writeFile with overwrite:false) all turn the OS guarantee into a language-level error.

Above the raw contract, many libraries layer policy on top of the same primitive. Installers and CLIs refuse to clobber user data: GitButler's macOS installer renames an existing ~/.local/bin/but to a .backup.<timestamp> file before symlinking, tauri's signer generate demands --force to replace a keypair, deno install -g aborts on an existing binary unless -f is passed, and october's media manager blocks uploads that would overwrite unless the user both posts force_overwrite and holds the media delete permission. Others use the error as a feature: mastra treats FileExistsError as create-once/lock semantics, CodeWhale's immutable artifact store accepts a re-write only if the bytes are identical and fails with AlreadyExists otherwise, and Hadoop's GCS connector uses generation-based preconditions so two concurrent creators race safely and the loser gets the exception.

From the caller's side the message usually arrives with little context beyond the path — the useful question is always 'why does that path already have something on it?' The dominant answers in this family are stale leftovers from a previous crashed or interrupted run (HDFS rbw temp files after a DataNode kill -9, half-finished SiYuan imports leaving assets behind, re-running a job against an uncleaned output dir), two writers pointed at the same location (two JobHistoryServers sharing a recovery store, two processes racing for the same name), and names that collide after normalization (claw-code sanitizing 'Code Review' and 'code-review' to the same file, sanitized artifact ids colliding, timestamp names generated twice within one second).

Details vary enough that you must read your library's contract. Whether overwrite is opt-in (Hadoop), opt-out (mastra), or forced via a CLI flag (tauri, deno install) is library-specific; whether a directory at the target is a hard error even with overwrite (Hadoop object connectors) or a different message entirely (viewfs mount-table errors like '/ is not a file. The directory / already exist at: ...') differs per implementation; and whether an identical-bytes rewrite is idempotent (CodeWhale) or always an error (remotion's codemods, which never overwrite scaffolded files) is a deliberate design choice, not a bug. One behavior is consistent across the family: none of these errors mean the filesystem is broken — they mean something is already at the path, and the software refuses to destroy it without an explicit decision.

Common causes

What usually fixes it

Documented occurrences

…and 72 more across the corpus — use search.

Honest provenance: generated on 2026-08-31 from AI-assisted analysis of the linked records. See how records are made.