pinpoint-apm/pinpoint · error · PluginException

File cannot be read

Error message

 File cannot be read

What it means

PluginJar.verify() checks Files.isReadable(file) after existence/regular-file checks and throws this PluginException when the process cannot read the plugin jar. It is a pre-flight permission check before opening the jar for the manifest.

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/plugin/PluginJar.java:81

            return new JarFile(pluginJar.toFile());
        } catch (IOException e) {
            throw new PluginException(pluginJar + " JarFile create error " + e.getCause(), e);
        }
    }

    public static PluginJar fromFilePath(Path path) {
        return new PluginJar(path);
    }

    private static void verify(Path file) {
        if (!Files.exists(file)) {
            throw new PluginException(file + " File does not exist");
        }
        if (!Files.isRegularFile(file)) {
            throw new PluginException(file + " is not a file");
        }
        if (!Files.isReadable(file)) {
            throw new PluginException(file + " File cannot be read");
        }
    }

    public URL getURL() {
        return url;
    }

    public JarFile getJarFile() {
        return jarFile;
    }

    public String getPluginId() {
        return manifest.getPluginId();
    }

    public String getPluginCompilerVersion() {
        return manifest.getPluginCompilerVersion();
    }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Grant read permission on the jar: chmod a+r <jar> (or chown to the agent user)
2. Verify the user running the JVM can read the file: sudo -u <agent-user> head -c1 <jar>
3. Fix deployment/CI so plugin jars are copied with world-readable permissions

Example fix

// shell before
-rw------- pinpoint-foo-plugin.jar
// shell after
chmod 644 pinpoint-foo-plugin.jar

if (!Files.isReadable(jarPath)) { throw new IllegalStateException("Agent user cannot read plugin jar: " + jarPath); }

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

try { PluginJar.createJarFile(jarPath); } catch (PluginException e) { log.error("Plugin jar unreadable: {}", jarPath, e); }

When it happens

Trigger: Calling PluginJar.createJarFile(path) on a jar file whose OS permissions deny read access to the pinpoint agent process user.

Common situations: Plugin jar deployed by root with 0600 permissions while the agent runs as another user, restrictive umask after manual upload, or container volume mounted read-only/non-readable for the agent UID.

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

• profileDirs traverse error
• I/O error getting type provider definitions
• is not a file
• Manifest error
• %s load fail Caused by:%s

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