arduino/Arduino · error · IOException

Could not create folder: {outputFile}

Error message

Could not create folder: {outputFile}

What it means

ArchiveExtractor throws this IOException while unzipping an archive when a directory entry cannot be created on disk: the target File neither exists nor can be created via mkdirs(). It typically indicates a filesystem-level problem (permissions, existing non-directory file at that path, disk full, or illegal path characters).

Source

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

        // 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);
          hardLinksMode.put(outputFile, mode);
        } else if (isSymLink) {
          symLinks.put(outputFile, linkName);
          symLinksModifiedTimes.put(outputFile, modifiedTime);
        } else {
          // Create the containing folder if not exists
          if (!outputFile.getParentFile().isDirectory()) {
            outputFile.getParentFile().mkdirs();
          }
          copyStreamToFile(in, size, outputFile);
          outputFile.setLastModified(modifiedTime);
        }

        // Set file/folder permission

View on GitHub (pinned to a0df6e0e83)

Solutions

1. Check that the parent directory of the extraction target exists, is writable by the current user, and contains no regular file with the same name as an archive directory entry
2. Clear the stale/partial extraction directory and re-extract (rm -rf the target, then retry)
3. Run with sufficient privileges or fix ownership (chown/chmod) of the destination folder
4. Verify disk free space and that the path length/characters are valid for the OS filesystem

Example fix

// before: extract into a path that may be blocked
extractor.extract(archive, new File("/usr/share/arduino/libraries/MyLib"));
// after: ensure a clean writable target
dir.mkdirs();
if (!dir.isDirectory() || !dir.canWrite()) throw new IllegalStateException("bad target");
extractor.extract(archive, dir);

File target = new File(destDir, entryName);
if (target.exists() && !target.isDirectory())
  throw new IllegalStateException("File blocks directory entry: " + target);
if (!destDir.canWrite()) throw new IllegalStateException("Dest not writable: " + destDir);

static boolean isExtractableDir(File f) {
  return !f.exists() || (f.isDirectory() && f.canWrite());
}

try {
  extractor.extract(archive, dir);
} catch (IOException e) {
  if (e.getMessage().startsWith("Could not create folder")) {
    // clean stale target and retry
    FileUtils.deleteQuietly(dir); dir.mkdirs(); extractor.extract(archive, dir);
  } else throw e;
}

When it happens

Trigger: extract() processes a zip/tar entry with isDirectory==true, outputFile does not yet exist, and File.mkdirs() returns false (parent dirs not creatable, permission denied, path segment occupied by a regular file, or name too long/invalid).

Common situations: Extracting a library or platform archive into an Arduino data directory with wrong ownership; a previous partial extraction left a file where a directory should be; extracting on a case-insensitive filesystem where entry names collide; read-only volume or full disk.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• Could not create directory "{0}"
• Error while extracting file {outputFile.getAbsolutePath()}
• Could not remove old version of {0}
• Could not replace {0}
• Failed to rename sketch folder

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