arduino/Arduino · error · IOException

Can't create folder {outputFile}, a file with the same name

Error message

Can't create folder {outputFile}, a file with the same name exists!

What it means

During extraction, when an entry is a directory, extract() checks whether a regular file already exists at the destination path. If it does and overwrite is false, it throws this IOException rather than clobbering or failing mid-write. This is a safety check so extraction never silently replaces a file with a folder.

Source

Thrown at arduino-core/src/cc/arduino/utils/ArchiveExtractor.java:208

          if (!linkName.startsWith(pathPrefix)) {
            throw new IOException("Invalid archive: it must contain a single root folder while file " + linkName + " is outside " + pathPrefix);
          }
          linkName = linkName.substring(pathPrefix.length());
          outputLinkedFile = new File(destFolder, linkName);
        }
        if (isSymLink) {
          // Symbolic links are referenced with relative paths
          outputLinkedFile = new File(linkName);
          if (outputLinkedFile.isAbsolute()) {
            System.err.println(I18n.format(tr("Warning: file {0} links to an absolute path {1}"), outputFile, outputLinkedFile));
            System.err.println();
          }
        }

        // Safety check
        if (isDirectory) {
          if (outputFile.isFile() && !overwrite) {
            throw new IOException("Can't create folder " + outputFile + ", a file with the same name exists!");
          }
        } else {
          // - isLink
          // - isSymLink
          // - anything else
          if (outputFile.exists() && !overwrite) {
            throw new IOException("Can't extract file " + outputFile + ", file already exists!");
          }
        }

        // Extract the entry
        if (isDirectory) {
          if (!outputFile.exists() && !outputFile.mkdirs()) {
            throw new IOException("Could not create folder: " + outputFile);
          }
          foldersTimestamps.put(outputFile, modifiedTime);
        } else if (isLink) {
          hardLinks.put(outputFile, outputLinkedFile);

View on GitHub (pinned to a0df6e0e83)

Solutions

  1. Delete the conflicting file (or clear the destination folder) and extract again
  2. Call extract with overwrite=true to replace existing files/directories
  3. Manually inspect the destination for stray files with the same names as the archive's folders and resolve the conflict

Example fix

// before
new ArchiveExtractor().extract(archive, destFolder, 1); // overwrite defaults to false
// after
new ArchiveExtractor().extract(archive, destFolder, 1, true); // allow replacing stale entries
Defensive patterns

Strategy: try-catch

Validate before calling

// detect file-vs-folder conflicts before extracting
if (destFolder.exists()) {
  Files.walk(destFolder.toPath()).filter(Files::isRegularFile).map(p -> p.getFileName().toString())
    .filter(n -> expectedArchiveDirNames.contains(n)).forEach(n -> { throw new IllegalStateException("Conflict: file " + n + " blocks archive folder"); });
}

Try / catch

try { extractor.extract(archive, dest, 1); } catch (IOException e) { if (e.getMessage().startsWith("Can't create folder")) { clearDestination(dest); extractor.extract(archive, dest, 1, true); } else { throw e; } }

Prevention

When it happens

Trigger: extract(file, dest, stripPath, overwrite=false) where the destination already contains a file whose name collides with a directory entry in the archive (e.g. an old partial install left a file where the archive has a folder).

Common situations: Reinstalling/upgrading a library into a destination where a previous layout used files at paths now occupied by directories; leftover temp/lock files colliding with archive directory names; installing into a non-empty destination folder.

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

AI-assisted analysis of arduino/Arduino@a0df6e0e83 (2026-09-06). Data as JSON: /api/errors/309cf95b5f133159. Report an issue: GitHub.