pinpoint-apm/pinpoint · error · PluginException

is not a file

Error message

 is not a file

What it means

PluginJar.verify() validates the path given to createJarFile() before opening the plugin jar. It throws this PluginException when the path exists but is not a regular file (e.g. a directory or special file). The library refuses to treat non-regular paths as jar sources.

Source

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

    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() {
        return manifest.getPluginId();
    }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Check the path with `ls -l` and confirm it is a regular .jar file, not a directory
2. Fix the pinpoint profiler configuration to point at the actual plugin jar file or the parent directory scanned for jars
3. Remove stale symlinks or special files at that path and redeploy the plugin jar

Example fix

// before
PluginJar.createJarFile(Path.of("/plugins"));
// after
PluginJar.createJarFile(Path.of("/plugins/pinpoint-foo-plugin.jar"));

if (!Files.isRegularFile(jarPath)) { throw new IllegalArgumentException("Plugin path is not a regular file: " + jarPath); }

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

try { PluginJar.createJarFile(jarPath); } catch (PluginException e) { log.error("Invalid plugin jar path {}: {}", jarPath, e.getMessage()); }

When it happens

Trigger: Calling PluginJar.createJarFile(path) where Files.isRegularFile(path) is false but the path exists — e.g. pointing the profiler plugin directory config at a directory itself instead of a .jar file inside it.

Common situations: Misconfigured profiler.plugin.pluginJarLocation (or plugin dir) option set to a directory, a symlink resolution leaving a directory path, or a mount point/socket path supplied instead of the jar.

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

• MalformedURL error
• I/O error getting type provider definitions
• File cannot be read
• Manifest error
• %s load fail Caused by:%s

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