pinpoint-apm/pinpoint · error · RuntimeException

Path IO error

Error message

 Path IO error

What it means

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.

Source

Thrown at agent-module/bootstraps/bootstrap/src/main/java/com/navercorp/pinpoint/bootstrap/agentdir/FileUtils.java:51

public final class FileUtils {

    private static final BootLogger logger = BootLogger.getLogger(FileUtils.class);

    private FileUtils() {
    }

    public static List<Path> listFiles(Path dirPath, String glob) {
        Objects.requireNonNull(dirPath, "dirPath");
        Objects.requireNonNull(glob, "glob");

        try (DirectoryStream<Path> paths = Files.newDirectoryStream(dirPath, glob)) {
            List<Path> list = new ArrayList<>();
            for (Path path : paths) {
                list.add(path);
            }
            return list;
        } catch (IOException e) {
            throw new RuntimeException(dirPath + " Path IO error" , e);
        }
    }

    public static Path subpathAfterLast(Path path, int lastIndex) {
        int end = path.getNameCount();
        int begin = end - Math.min(end, lastIndex);
        return path.subpath(begin, end);
    }

    public static Path subpathAfter(Path path, int beginIndex) {
        int end = path.getNameCount();
        int begin = Math.min(beginIndex, end);
        return path.subpath(begin, end);
    }

    public static Path toRealPath(Path path) {
        try {
            return path.toRealPath().normalize();

View on GitHub (pinned to 744c3d3075)

Solutions

1. Verify the directory exists and is a directory: run `ls -la <dirPath>` (or Files.isDirectory) before calling listFiles.
2. Fix permissions so the JVM user can read/execute the directory (chmod u+rx or chown).
3. Correct the path value at the call site or configuration that produced the wrong dirPath.
4. Inspect the wrapped IOException cause for the real filesystem error (e.g. 'Not a directory', 'Permission denied') and address it.

Example fix

// before
List<Path> jars = FileUtils.listFiles(Paths.get("/opt/pinpoint-agent/lig"), 1); // typo 'lig'
// after
Path dir = Paths.get("/opt/pinpoint-agent/lib");
if (Files.isDirectory(dir) && Files.isReadable(dir)) {
    List<Path> jars = FileUtils.listFiles(dir, 1);
}

Path dir = Paths.get(dirPathString);
if (!Files.isDirectory(dir)) {
    throw new IllegalArgumentException("Not a directory: " + dir.toAbsolutePath());
}
if (!Files.isReadable(dir)) {
    throw new IllegalStateException("Directory not readable: " + dir.toAbsolutePath());
}

try {
    List<Path> files = FileUtils.listFiles(dirPath, lastIndex);
} catch (RuntimeException e) {
    Throwable cause = e.getCause(); // IOException with the real reason
    logger.error("Failed to list {}: {}", dirPath, cause == null ? e : cause.getMessage());
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• %s load fail Caused by:%s
• MalformedURL error
• is directory
• not file
• can read

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/34d1646ad9b7b2d9. Report an issue: GitHub.