arduino/Arduino · error · IOException

Failed to rename " " to

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.

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
• Failed to rename sketch folder
• Could not create directory
• Could not create folder
• Could not remove old version of

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

Appendix: 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)