pinpoint-apm/pinpoint · error · PluginException

JarFile create error

Error message

 JarFile create error 

What it means

PluginJar.createJarFile() verifies the plugin path and opens it as a JarFile. If opening throws IOException (corrupt zip, unreadable file, wrong format), it wraps it in PinpointException with 'JarFile create error'. The agent cannot load the plugin jar, so plugin loading fails at startup.

Solutions

1. Verify the jar with 'jar tf <file>' or unzip -t to confirm it is a valid zip archive
2. Re-download/re-copy the plugin jar and retry
3. Ensure the plugin file is readable by the agent process user and on a stable filesystem
4. Catch PinpointException around plugin loading and skip/log the offending jar instead of aborting the agent

Example fix

// before
PluginJar plugin = PluginJar.fromFilePath(Paths.get("/plugins/broken.jar"));
// after
if (Files.isReadable(p) && isZipArchive(p)) { PluginJar plugin = PluginJar.fromFilePath(p); }

Path p = Paths.get(pluginPath);
if (!Files.exists(p) || !Files.isRegularFile(p)) throw new IllegalArgumentException("not a file: " + p);
try (JarFile jf = new JarFile(p.toFile())) { /* valid jar */ }
catch (IOException e) { throw new IllegalStateException("corrupt plugin jar: " + p, e); }

try {
    PluginJar plugin = PluginJar.fromFilePath(p);
} catch (PluginException e) {
    logger.error("Cannot load plugin {}: {}", p, e.getMessage());
}

When it happens

Trigger: PluginJar.fromFilePath()/new PluginJar(path) called on a path whose file passes existence checks but cannot be opened as a jar — corrupt download, non-zip file, locked file, or IO error during open.

Common situations: Truncated plugin jar from a failed copy/download; plugin directory containing a non-jar file; file permission or mount issues in containers; verify() passing but file changed between check and open (race).

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

• File does not exist
• bytecode read fail scanner
• create fail Caused by:
• defineAgentPackage fail: Caused by:
• Duplicate order found for plugin

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

Appendix: source

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

        this.jarFile = createJarFile(path);
        this.manifest = PluginManifest.of(jarFile);
    }


    private URL toURL(Path file) {
        try {
            return file.toUri().toURL();
        } catch (MalformedURLException e) {
            throw new PluginException(file + " toURL error", e);
        }
    }

    private static JarFile createJarFile(Path pluginJar) {
        try {
            verify(pluginJar);
            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");
        }
    }

View on GitHub (pinned to 744c3d3075)