pinpoint-apm/pinpoint · error · PluginException

File does not exist

Error message

 File does not exist

What it means

PluginJar.verify() pre-checks a plugin path before opening it: the file must exist, be a regular file, and be readable. When Files.exists() returns false it throws PinpointException '<path> File does not exist'. This fail-fast check gives a clearer message than letting JarFile open fail.

Solutions

1. Confirm the path exists (ls the plugins directory) and correct the configured plugins dir or filename
2. Use absolute paths when constructing the plugin jar Path
3. Ensure deployment packages actually ship the plugin jar into the expected directory
4. Add a startup check listing missing plugin files before initializing the plugin loader

Example fix

// before
PluginJar plugin = PluginJar.fromFilePath(Paths.get("plugins/my-plugin.jar"));
// after
Path p = Paths.get("/opt/pinpoint/plugins/my-plugin.jar");
if (!Files.exists(p)) throw new ConfigException("missing plugin: " + p);
PluginJar plugin = PluginJar.fromFilePath(p);

Path p = Paths.get(pluginPath).toAbsolutePath().normalize();
if (!Files.exists(p)) throw new IllegalArgumentException("plugin jar does not exist: " + p);
if (!Files.isRegularFile(p)) throw new IllegalArgumentException("not a regular file: " + p);
if (!Files.isReadable(p)) throw new IllegalArgumentException("not readable: " + p);

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

When it happens

Trigger: PluginJar.fromFilePath() or new PluginJar(path) called with a path that does not exist on disk — wrong directory, mistyped filename, or the jar was deleted/moved before loading.

Common situations: Wrong plugins directory configured for the agent; plugin jar renamed or removed during redeployment; relative path resolved against a different working directory; container image missing the plugin.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• JarFile create error
• AgentPath not found path:
• Duplicate order found for plugin
• Failed to load plugin class
• not found

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

Appendix: source

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

        }
    }

    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");
        }
    }

    public URL getURL() {
        return url;
    }

    public JarFile getJarFile() {
        return jarFile;
    }

    public String getPluginId() {

View on GitHub (pinned to 744c3d3075)