arduino/Arduino · error · IOException

'Unable to list files of library in ' + libFolder

Error message

'Unable to list files of library in ' + libFolder

What it means

After determining the layout (recursive vs flat), UserLibrary.create() calls libFolder.listFiles() to scan the root for development leftovers. listFiles() returns null when the path is not a readable directory (does not exist, is a file, or an I/O error occurs), and create() turns that null into this IOException.

Source

Thrown at arduino-core/src/processing/app/packages/UserLibrary.java:114

      if (!properties.containsKey(p))
        throw new IOException("Missing '" + p + "' from library");

    // Check layout
    LibraryLayout layout;
    File srcFolder = new File(libFolder, "src");

    if (srcFolder.exists() && srcFolder.isDirectory()) {
      // Layout with a single "src" folder and recursive compilation
      layout = LibraryLayout.RECURSIVE;
    } else {
      // Layout with source code on library's root and "utility" folders
      layout = LibraryLayout.FLAT;
    }

    // Warn if root folder contains development leftovers
    File[] files = libFolder.listFiles();
    if (files == null) {
      throw new IOException("Unable to list files of library in " + libFolder);
    }

    // Extract metadata info
    String architectures = properties.get("architectures");
    if (architectures == null)
      architectures = "*"; // defaults to "any"
    List<String> archs = new ArrayList<>();
    for (String arch : architectures.split(","))
      archs.add(arch.trim());

    String category = properties.get("category");
    if (category == null) {
      category = "Uncategorized";
    }
    if (!Constants.LIBRARY_CATEGORIES.contains(category)) {
      category = "Uncategorized";
    }

View on GitHub (pinned to a0df6e0e83)

Solutions

1. Verify the path exists and is a real directory (ls the path); re-create or re-download the library if it is gone
2. Fix filesystem permissions on the library folder so the IDE user can list it
3. Refresh/rescan the library manager index so stale entries are dropped
4. Remove broken symlinks to unmounted volumes or non-existent targets

Example fix

// before: creating a library from a possibly stale path
UserLibrary lib = UserLibrary.create(new File(librariesDir, name));
// after: guard first
File dir = new File(librariesDir, name);
if (!dir.isDirectory()) { /* rescan index / skip */ }
UserLibrary lib = UserLibrary.create(dir);

if (libFolder == null || !libFolder.isDirectory()) {
  throw new IllegalArgumentException("Not a listable library folder: " + libFolder);
}

boolean isListableDir(File f) {
  return f != null && f.isDirectory() && f.listFiles() != null;
}

try {
  UserLibrary lib = UserLibrary.create(libFolder);
} catch (IOException e) {
  if (e.getMessage().startsWith("Unable to list files")) { /* rescan index, skip or reinstall library */ }
}

When it happens

Trigger: Calling UserLibrary.create(libFolder) with a File that is not a listable directory: a regular file instead of a folder, a folder deleted between existence checks and the call, or insufficient OS permissions to enumerate its contents.

Common situations: A stale index entry pointing at a library folder that was deleted; a library 'folder' that is actually a symlink to a file or an unmounted drive; OS permission problems in sketchbook/libraries; race with another process cleaning the libraries directory.

Related errors

• 'arch' folder is no longer supported! See http://goo.gl/gfFJ
• Can't download {0}: invalid filename or exinsting directory
• no headers files (.h) found in {0}
• Archive format not supported.
• Invalid archive: it must contain a single root folder

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