arduino/Arduino · error · IOException

The sketch already contains a file named "{0}"

Error message

The sketch already contains a file named "{0}"

What it means

checkNewFilename verifies the new file name is not already part of the sketch and throws IOException when findFileIndex locates it among existing sketch files. Called by rename operations and Sketch.addFile to keep sketch file names unique.

Source

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

    return new File(newFolder, newPrimary);
  }

  /**
   * Check if renaming or adding a file would cause a problem because
   * the file already exists in this sketch. If so, an IOEXception is
   * thrown.
   *
   * @param newFile
   *          The filename of the new file, or the new name for an
   *          existing file.
   */
  protected void checkNewFilename(File newFile) throws IOException {
    // Verify that the sketch doesn't have a filem with the new name
    // already, other than the current primary (index 0)
    if (findFileIndex(newFile) >= 0) {
      String msg = I18n.format(tr("The sketch already contains a file named \"{0}\""), newFile.getName());
      throw new IOException(msg);
    }

  }

  /**
   * Rename this sketch' folder to the given name. Unlike saveAs(), this
   * 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.
   */

View on GitHub (pinned to a0df6e0e83)

Solutions

1. Pick a different name not used by any tab in the sketch
2. Delete the existing conflicting file first if it is obsolete
3. Before addFile, scan the sketch folder for a file with the same name
4. Uniquify programmatically (append a suffix) before adding

Example fix

// before
sketchFile.renameTo("sensor.ino"); // fails if sensor.ino exists
// after
String newName = "sensor.ino";
if (sketch.folderFile(newName).exists()) {
  newName = "sensor_copy.ino";
}
sketchFile.renameTo(newName);

boolean taken = Arrays.stream(sketch.getFiles())
    .anyMatch(f -> f.getFileName().equals(newName));
if (taken) throw new IllegalArgumentException("Name in use: " + newName);

static boolean nameIsFree(Sketch sketch, String newName) {
  return sketch.findFileIndex(new File(sketch.getFolder(), newName)) < 0;
}

try {
  sketchFile.renameTo(newName);
} catch (IOException e) {
  System.err.println("Duplicate name: " + e.getMessage());
}

When it happens

Trigger: Renaming a sketch tab to a name that another tab already uses, or addFile() importing a file whose name collides with an existing sketch file (other than the primary at index 0).

Common situations: Adding a .h/.cpp whose name matches an existing tab; renaming a tab to an existing tab name (e.g. "sketch" variants); importing files from a library folder containing duplicates.

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

• No valid code files found
• no headers files (.h) found in {0}
• 'Missing '' + p + '' from library'

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