arduino/Arduino · error · IOException

Failed to rename "{0}" to "{1}"

Error message

Failed to rename "{0}" to "{1}"

What it means

SketchFile.renameTo validates the new name against the sketch, then performs the OS rename of the underlying file; this IOException is thrown when the file is missing or the rename syscall fails. It is normally reached via nameCode when renaming a sketch tab.

Source

Thrown at arduino-core/src/processing/app/SketchFile.java:184

  /**
   * Rename the given file to get the given name.
   *
   * @param newName
   *          The new name, including extension, excluding directory
   *          name.
   * @throws IOException
   *           When a problem occurs, or is expected to occur. The error
   *           message should be already translated.
   */
  public void renameTo(String newName) throws IOException {
    File newFile = new File(file.getParentFile(), newName);
    sketch.checkNewFilename(newFile);
    if (!file.exists() || file.renameTo(newFile)) {
      renamedTo(newFile);
    } else {
      String msg = I18n.format(tr("Failed to rename \"{0}\" to \"{1}\""), file.getName(), newName);
      throw new IOException(msg);
    }
  }

  /**
   * Should be called when this file was renamed and renameTo could not
   * be used (e.g. when renaming the entire sketch directory).
   */
  protected void renamedTo(File what) {
    file = what;
  }

  /*
   * Returns the filename include extension.
   */
  public String getFileName() {
    return file.getName();
  }

View on GitHub (pinned to a0df6e0e83)

Solutions

1. Verify the file still exists in the sketch folder and restore it if deleted
2. Close external editors holding the file open
3. Pick a name that differs beyond case, or rename in two steps (foo.ino -> foo2.ino -> Foo.ino)
4. Check write permission on the sketch folder

Example fix

// before
sketchFile.renameTo("Led"); // may fail if led.ino locked or case-only rename on Windows
// after
File f = sketchFile.getFile();
if (f.exists() && f.getParentFile().canWrite()) {
  File tmp = new File(f.getParentFile(), "tmp_renameme.ino");
  if (f.renameTo(tmp) && tmp.renameTo(new File(f.getParentFile(), "Led.ino"))) {
    sketchFile.renamedTo(new File(f.getParentFile(), "Led.ino"));
  }
}

if (!file.exists()) throw new IllegalStateException("Source file missing: " + file);
if (!file.getParentFile().canWrite()) throw new IllegalStateException("Folder not writable");

try {
  sketchFile.renameTo(newName);
} catch (IOException e) {
  System.err.println("Rename failed: " + e.getMessage());
  // offer Save As or manual file move
}

When it happens

Trigger: Renaming a tab/file where File.renameTo returns false or file.exists() is false: file deleted externally, locked by another process, target name exists on a case-insensitive filesystem, or unwritable directory.

Common situations: Renaming a tab while the file is open/locked in an external editor; the file was removed on disk behind the IDE's back; renaming only to change case on Windows/macOS.

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 sketch folder
• 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/643a3e64aa4b7531. Report an issue: GitHub.