{"record":{"id":"34d1646ad9b7b2d9","repo":"pinpoint-apm/pinpoint","slug":"path-io-error","errorCode":null,"errorMessage":" Path IO error","messagePattern":" Path IO error","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/agentdir/FileUtils.java","lineNumber":51,"sourceCode":"public final class FileUtils {\n\n    private static final BootLogger logger = BootLogger.getLogger(FileUtils.class);\n\n    private FileUtils() {\n    }\n\n    public static List<Path> listFiles(Path dirPath, String glob) {\n        Objects.requireNonNull(dirPath, \"dirPath\");\n        Objects.requireNonNull(glob, \"glob\");\n\n        try (DirectoryStream<Path> paths = Files.newDirectoryStream(dirPath, glob)) {\n            List<Path> list = new ArrayList<>();\n            for (Path path : paths) {\n                list.add(path);\n            }\n            return list;\n        } catch (IOException e) {\n            throw new RuntimeException(dirPath + \" Path IO error\" , e);\n        }\n    }\n\n    public static Path subpathAfterLast(Path path, int lastIndex) {\n        int end = path.getNameCount();\n        int begin = end - Math.min(end, lastIndex);\n        return path.subpath(begin, end);\n    }\n\n    public static Path subpathAfter(Path path, int beginIndex) {\n        int end = path.getNameCount();\n        int begin = Math.min(beginIndex, end);\n        return path.subpath(begin, end);\n    }\n\n    public static Path toRealPath(Path path) {\n        try {\n            return path.toRealPath().normalize();","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/agentdir/FileUtils.java#L33-L69","documentation":"FileUtils.listFiles(Path dirPath, ...) walks a directory and returns the list of contained files. If any I/O operation on the path fails (directory unreadable, does not exist, is not a directory, filesystem error), the caught IOException is rethrown as RuntimeException with \"<dirPath> Path IO error\". This is a fail-fast wrapper so bootstrap code does not silently continue with an empty file list.","triggerScenarios":"Calling FileUtils.listFiles(dirPath, ...) where the directory cannot be listed: path does not exist, path is a regular file not a directory, insufficient read permission, or an underlying filesystem I/O error during Files.walk/newDirectoryStream.","commonSituations":"Wrong path passed to agent tooling (typo or relative path resolved differently); directory deleted between existence check and listing; permission problems after copying an agent dir as another user (root-created dirs with restrictive modes); network/USB mounts going away mid-scan.","solutions":["Verify the directory exists and is a directory: run `ls -la <dirPath>` (or Files.isDirectory) before calling listFiles.","Fix permissions so the JVM user can read/execute the directory (chmod u+rx or chown).","Correct the path value at the call site or configuration that produced the wrong dirPath.","Inspect the wrapped IOException cause for the real filesystem error (e.g. 'Not a directory', 'Permission denied') and address it."],"exampleFix":"// before\nList<Path> jars = FileUtils.listFiles(Paths.get(\"/opt/pinpoint-agent/lig\"), 1); // typo 'lig'\n// after\nPath dir = Paths.get(\"/opt/pinpoint-agent/lib\");\nif (Files.isDirectory(dir) && Files.isReadable(dir)) {\n    List<Path> jars = FileUtils.listFiles(dir, 1);\n}","handlingStrategy":"validation","validationCode":"Path dir = Paths.get(dirPathString);\nif (!Files.isDirectory(dir)) {\n    throw new IllegalArgumentException(\"Not a directory: \" + dir.toAbsolutePath());\n}\nif (!Files.isReadable(dir)) {\n    throw new IllegalStateException(\"Directory not readable: \" + dir.toAbsolutePath());\n}","typeGuard":null,"tryCatchPattern":"try {\n    List<Path> files = FileUtils.listFiles(dirPath, lastIndex);\n} catch (RuntimeException e) {\n    Throwable cause = e.getCause(); // IOException with the real reason\n    logger.error(\"Failed to list {}: {}\", dirPath, cause == null ? e : cause.getMessage());\n    throw e;\n}","preventionTips":["Always pass absolute, canonical paths to listFiles.","Check Files.isDirectory && Files.isReadable before scanning.","Run the JVM under a user that owns or can read the agent directory.","Log the wrapped IOException cause — it names the true filesystem failure."],"tags":["io","filesystem","directory","runtime-exception"],"backgroundTag":"file-read-failed","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}