arduino/Arduino · error · IOException

Failed to rename sketch folder

Error message

Failed to rename sketch folder

What it means

renameTo first validates the target via checkNewFoldername, then performs the actual filesystem rename of the sketch folder. It throws IOException when File.renameTo returns false, i.e. the OS-level rename failed after validation passed.

Source

Thrown at arduino-core/src/processing/app/Sketch.java:298

   * moves the sketch directory, not leaving anything in the old place.
   * This operation does not *save* the sketch, so the files on disk are
   * moved, but not modified.
   *
   * @param newFolder
   *          The new folder name for this sketch. The new primary
   *          file's name will be derived from this.
   *
   * @throws IOException
   *           When a problem occurs. The error message should be
   *           already translated.
   */
  public void renameTo(File newFolder) throws IOException {
    // Check intended rename (throws if there is a problem)
    File newPrimary = checkNewFoldername(newFolder);

    // Rename the sketch folder
    if (!getFolder().renameTo(newFolder))
      throw new IOException(tr("Failed to rename sketch folder"));

    folder = newFolder;

    // Tell each file about its new name
    for (SketchFile file : files)
      file.renamedTo(new File(newFolder, file.getFileName()));

    // And finally, rename the primary file
    getPrimaryFile().renameTo(newPrimary.getName());
  }


  public SketchFile addFile(String newName) throws IOException {
    // Check the name will not cause any conflicts
    File newFile = new File(folder, newName);
    checkNewFilename(newFile);

    // Add a new sketchFile

View on GitHub (pinned to a0df6e0e83)

Solutions

1. Close any programs that have files in the sketch folder open
2. Rename to a path on the same filesystem/volume
3. Check write permission on the sketch's parent directory
4. Retry after unlocking files; on Windows close Explorer windows inside the folder
5. As a fallback, copy the folder manually and delete the original

if (!getFolder().getParentFile().canWrite()) throw new IllegalStateException("Parent dir not writable");
if (!newFolder.getParentFile().equals(getFolder().getParentFile())) throw new IllegalStateException("Cross-volume rename");

try {
  sketch.renameTo(newFolder);
} catch (IOException e) {
  // fallback: copy + delete
  FileUtils.copyDirectory(sketch.getFolder(), newFolder);
  FileUtils.deleteDirectory(sketch.getFolder());
}

When it happens

Trigger: Sketch.renameTo(newFolder) where the OS cannot move the folder: target on a different filesystem/mount, folder locked by an open file handle, or insufficient write permission on the parent directory.

Common situations: Sketch open in another program (editor, file manager) holding handles; renaming across drives; read-only network share or synced folder; on Windows a file inside is open and locked.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Could not replace {0}
• Failed to rename "{0}" to "{1}"
• Could not create folder: {outputFile}
• Could not remove old version of {0}
• Sorry, the folder "{0}" already exists.

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