{"record":{"id":"88f8d36d77ef9a73","repo":"arduino/Arduino","slug":"unable-to-list-files-of-library-in-libfolder","errorCode":null,"errorMessage":"'Unable to list files of library in ' + libFolder","messagePattern":"'Unable to list files of library in ' \\+ libFolder","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"arduino-core/src/processing/app/packages/UserLibrary.java","lineNumber":114,"sourceCode":"      if (!properties.containsKey(p))\n        throw new IOException(\"Missing '\" + p + \"' from library\");\n\n    // Check layout\n    LibraryLayout layout;\n    File srcFolder = new File(libFolder, \"src\");\n\n    if (srcFolder.exists() && srcFolder.isDirectory()) {\n      // Layout with a single \"src\" folder and recursive compilation\n      layout = LibraryLayout.RECURSIVE;\n    } else {\n      // Layout with source code on library's root and \"utility\" folders\n      layout = LibraryLayout.FLAT;\n    }\n\n    // Warn if root folder contains development leftovers\n    File[] files = libFolder.listFiles();\n    if (files == null) {\n      throw new IOException(\"Unable to list files of library in \" + libFolder);\n    }\n\n    // Extract metadata info\n    String architectures = properties.get(\"architectures\");\n    if (architectures == null)\n      architectures = \"*\"; // defaults to \"any\"\n    List<String> archs = new ArrayList<>();\n    for (String arch : architectures.split(\",\"))\n      archs.add(arch.trim());\n\n    String category = properties.get(\"category\");\n    if (category == null) {\n      category = \"Uncategorized\";\n    }\n    if (!Constants.LIBRARY_CATEGORIES.contains(category)) {\n      category = \"Uncategorized\";\n    }\n","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/arduino/Arduino/blob/a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee/arduino-core/src/processing/app/packages/UserLibrary.java#L96-L132","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the path exists and is a real directory (ls the path); re-create or re-download the library if it is gone","Fix filesystem permissions on the library folder so the IDE user can list it","Refresh/rescan the library manager index so stale entries are dropped","Remove broken symlinks to unmounted volumes or non-existent targets"],"exampleFix":"// before: creating a library from a possibly stale path\nUserLibrary lib = UserLibrary.create(new File(librariesDir, name));\n// after: guard first\nFile dir = new File(librariesDir, name);\nif (!dir.isDirectory()) { /* rescan index / skip */ }\nUserLibrary lib = UserLibrary.create(dir);","handlingStrategy":"validation","validationCode":"if (libFolder == null || !libFolder.isDirectory()) {\n  throw new IllegalArgumentException(\"Not a listable library folder: \" + libFolder);\n}","typeGuard":"boolean isListableDir(File f) {\n  return f != null && f.isDirectory() && f.listFiles() != null;\n}","tryCatchPattern":"try {\n  UserLibrary lib = UserLibrary.create(libFolder);\n} catch (IOException e) {\n  if (e.getMessage().startsWith(\"Unable to list files\")) { /* rescan index, skip or reinstall library */ }\n}","preventionTips":["Verify the path is a real, readable directory before registering it with the library manager","Periodically rescan/clean sketchbook/libraries to purge deleted folders and broken symlinks","Fix OS permissions on the libraries directory"],"tags":["arduino","library","filesystem","io"],"backgroundTag":"directory-not-found","analyzedSha":"a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee","analyzedAt":"2026-09-06T10:13:38.901Z","contentChangedAt":"2026-09-06T10:13:38.901Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}