pinpoint-apm/pinpoint · error · IllegalArgumentException

can read

Error message

 can read

What it means

Thrown by JarFileUtils.openJarFile when the target path exists and is a regular file but is not readable by the current process. The utility pre-validates readability with Files.isReadable before attempting to open the jar, so this error surfaces instead of a raw FileSystemException from JarFile.

Source

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

/**
 * @author Woonduk Kang(emeroad)
 */
final class JarFileUtils {

    public static JarFile openJarFile(Path path) {
        Objects.requireNonNull(path, "path");

        if (!Files.exists(path)) {
            throw new IllegalArgumentException(path + " not found");
        }
        if (Files.isDirectory(path)) {
            throw new IllegalArgumentException(path + " is directory");
        }
        if (!Files.isRegularFile(path)) {
            throw new IllegalArgumentException(path + " not file");
        }
        if (!Files.isReadable(path)) {
            throw new IllegalArgumentException(path + " can read");
        }
        try {
            return new JarFile(path.toFile());
        } catch (IOException e) {
            throw new IllegalStateException(path + " create fail Caused by:" + e.getMessage(), e);
        }
    }
}

View on GitHub (pinned to 744c3d3075)

Solutions

  1. Run the JVM/agent as a user with read permission on the jar path
  2. chmod/chown the jar file so the running user can read it (e.g. chmod o+r <jar> or chown)
  3. Check parent directory execute/search permissions which can also block access
  4. Verify path points to the correct file; re-extract the agent distribution with correct permissions

Example fix

// before
Path jar = Paths.get("/opt/pinpoint/agent/pinpoint-bootstrap.jar"); // owned by root, mode 600
JarFile jf = JarFileUtils.openJarFile(jar); // throws 'can read'
// after
// as admin: chown pinpoint:pinpoint /opt/pinpoint/agent/pinpoint-bootstrap.jar && chmod 644 ...
JarFile jf = JarFileUtils.openJarFile(jar); // OK
Defensive patterns

Strategy: validation

Validate before calling

if (!Files.isRegularFile(path)) throw new IllegalStateException("not a readable jar file: " + path);
if (!Files.isReadable(path)) throw new IllegalStateException("no read permission: " + path);

Type guard

boolean isReadableJar(Path p) { return Files.isRegularFile(p) && Files.isReadable(p); }

Try / catch

try { JarFile jf = JarFileUtils.openJarFile(path); } catch (IllegalArgumentException e) { log.error("cannot read jar: {}", e.getMessage()); }

Prevention

When it happens

Trigger: Calling openJarFile(Path) on a jar whose OS permissions deny read access to the current user (e.g. root-owned jar, or restrictive chmod).

Common situations: Agent deployed/extracted by another user (root) so the pinpointer user cannot read jars in the agent directory; restrictive umask during agent installation; files copied from archives losing read bits.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

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