arduino/Arduino · error · IOException

no headers files (.h) found in {0}

Error message

no headers files (.h) found in {0}

What it means

LibrariesIndexer.scanLibrary() treats a folder without library.properties as a legacy (1.0-format) library and derives its source folder; BaseNoGui.headerListFromIncludePath() must then find at least one .h file. If none exist, an IOException is thrown because the folder is not a usable legacy library.

Source

Thrown at arduino-core/src/cc/arduino/contributions/libraries/LibrariesIndexer.java:219

      try {
        scanLibrary(new UserLibraryFolder(subfolder, folderDesc.location));
      } catch (IOException e) {
        System.out.println(I18n.format(tr("Invalid library found in {0}: {1}"), subfolder, e.getMessage()));
      }
    }
  }

  private void scanLibrary(UserLibraryFolder folderDesc) throws IOException {
    // A library is considered "legacy" if it doesn't contains
    // a file called "library.properties"
    File check = new File(folderDesc.folder, "library.properties");
    if (!check.exists() || !check.isFile()) {
      // Create a legacy library and exit
      LegacyUserLibrary lib = LegacyUserLibrary.create(folderDesc);
      String[] headers = BaseNoGui.headerListFromIncludePath(lib.getSrcFolder());
      if (headers.length == 0) {
        throw new IOException(format(tr("no headers files (.h) found in {0}"), lib.getSrcFolder()));
      }
      addToInstalledLibraries(lib);
      return;
    }

    // Create a regular library
    UserLibrary lib = UserLibrary.create(folderDesc);
    String[] headers = BaseNoGui.headerListFromIncludePath(lib.getSrcFolder());
    if (headers.length == 0) {
      throw new IOException(format(tr("no headers files (.h) found in {0}"), lib.getSrcFolder()));
    }
    addToInstalledLibraries(lib);

    Location loc = lib.getLocation();
    if (loc != Location.CORE && loc != Location.REFERENCED_CORE) {
      // Check if we can find the same library in the index
      // and mark it as installed
      ContributedLibrary foundLib = index.find(lib.getName(), lib.getVersion());

View on GitHub (pinned to a0df6e0e83)

Solutions

1. Add a library.properties file so the folder is treated as a modern library with explicit layout, or place at least one .h file in the legacy root/src folder.
2. Remove the offending folder from the libraries directory if it is not actually a library.
3. Reinstall the library properly via Library Manager so the layout matches the expected format.
4. Check extraction nesting: headers must be directly in the library root (legacy) or in the src folder declared by library.properties.

Example fix

// before (broken legacy library)
libraries/MyLib/MyLib.cpp   // no .h anywhere
// after
libraries/MyLib/MyLib.h     // header present, or add library.properties + src/MyLib.h

File dir = libraryFolder;
boolean hasProps = new File(dir, "library.properties").isFile();
if (!hasProps && BaseNoGui.headerListFromIncludePath(dir).length == 0) {
  throw new IllegalStateException("Not a valid legacy library: no .h in " + dir);
}

try { indexer.scanInstalledLibraries(); } catch (IOException e) { if (e.getMessage().contains("no headers files")) { skipOrRemoveInvalidLibrary(e); } else { throw e; } }

When it happens

Trigger: scanLibrary() encounters an installed-library folder whose 'library.properties' is missing or not a regular file, and the derived src folder contains zero .h header files.

Common situations: A user manually copied a folder containing only sources with extensions other than .h (or only .cpp/.hpp) into the libraries directory; an empty or junk folder inside ~/Arduino/libraries; a library zip extracted with an extra nesting level so headers aren't where the layout expects.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Can't download {0}: invalid filename or exinsting directory
• Can't create folder {outputFile}, a file with the same name
• Can't extract file {outputFile}, file already exists!
• 'arch' folder is no longer supported! See http://goo.gl/gfFJ
• 'Missing '' + p + '' from library'

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