What causes "profileDirs traverse error " in pinpoint-apm/pinpoint?

Check read/execute permissions on the agent's profiles directory for the JVM user: chmod -R u+rX profiles

pinpoint-apm/pinpoint · error · RuntimeException

profileDirs traverse error

Error message

profileDirs traverse error

What it means

AgentDirectory.getProfileDirs() walks the profiles directory (DirectoryStream) and wraps any IOException in RuntimeException 'profileDirs traverse error <profilesPath>'. This means the profiles directory could not be read/traversed, typically due to permissions or it being removed/replaced mid-scan.

Source

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

        return this.agentDirPath.resolve(fileName);
    }

    public List<Path> getProfileDirs() {
        List<Path> fileList = new ArrayList<>();

        final Path profilesPath = getProfilesPath();

        try (DirectoryStream<Path> stream = Files.newDirectoryStream(profilesPath)) {
            for (Path path : stream) {
                if (Files.isDirectory(path)) {
                    final Path fileName = path.getFileName();
                    if (fileName != null) {
                        fileList.add(fileName);
                    }
                }
            }
        } catch (IOException e) {
            throw new RuntimeException("profileDirs traverse error " + profilesPath, e);
        }
        return fileList;
    }

}

View on GitHub (pinned to 744c3d3075)

Solutions

Check read/execute permissions on the agent's profiles directory for the JVM user: chmod -R u+rX profiles
Verify the profiles directory exists in the agent installation and re-extract if missing
Point the agent at a complete, unmodified agent distribution
Check mount/volume health (NFS, container mounts) if I/O errors persist

Example fix

// before
ls -l /opt/pinpoint-agent/profiles  ->  permission denied
// after
chmod -R u+rX /opt/pinpoint-agent/profiles && ls /opt/pinpoint-agent/profiles  # release, dev, local

Defensive patterns

Strategy: try-catch

Validate before calling

Path profiles = Paths.get("/opt/pinpoint-agent/profiles");
if (!Files.isDirectory(profiles) || !Files.isReadable(profiles)) {
    throw new IllegalStateException("profiles dir unreadable: " + profiles);
}

Type guard

boolean isReadableDir(Path p) {
    return p != null && Files.isDirectory(p) && Files.isReadable(p);
}

Try / catch

try {
    AgentDirectory dir = resolver.resolve();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("profileDirs traverse error")) {
        // log profilesPath, check permissions/mount, re-extract agent dir
    }
    throw e;
}

Prevention

Run the JVM as a user with read access to the whole agent directory
Keep the agent directory on a reliable local filesystem rather than flaky network mounts
Verify the profiles directory exists after every agent upgrade
Watch audit logs for external processes modifying/deleting the agent dir at startup

When it happens

Trigger: IOException from DirectoryStream iteration over profilesPath: directory lacks read permission, was deleted, or an I/O error occurred while listing entries.

Common situations: Wrong user permissions on the agent directory; profiles folder deleted or renamed in a customized distribution; NFS/locked-volume I/O errors when the agent starts.

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

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