pinpoint-apm/pinpoint · error · IllegalArgumentException

not file

Error message

 not file

What it means

JarFileUtils.openJarFile(Path) requires a regular file: if Files.isRegularFile(path) is false (and it is not a directory — that case is caught earlier) it throws IllegalArgumentException with "<path> not file". This catches special files (symlink loops, devices, sockets, FIFOs, broken symlinks that pass exists-checks inconsistently) that cannot be opened as a JarFile.

Source

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

import java.util.Objects;
import java.util.jar.JarFile;

/**
 * @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. Verify the entry is a real file: `stat <path>` / Files.isRegularFile(path); remove or replace broken symlinks and special files.
2. Re-deploy the JAR (copy the real file) if a symlink is dangling or was replaced by a pipe/socket.
3. Filter scan results with Files.isRegularFile before calling openJarFile.
4. Check for symlink loops (Files.isSymbolicLink + toRealPath) and use the resolved real path.

Example fix

// before
JarFile jar = JarFileUtils.openJarFile(path); // path is a dangling symlink
// after
Path real = path.toAbsolutePath();
if (Files.isSymbolicLink(path)) {
    real = Files.readSymbolicLink(path).toAbsolutePath();
}
if (Files.isRegularFile(real)) {
    JarFile jar = JarFileUtils.openJarFile(real);
}

Path real = candidate;
if (Files.isSymbolicLink(candidate)) {
    real = candidate.toRealPath();
}
if (!Files.isRegularFile(real)) {
    throw new IllegalArgumentException("Not a regular file: " + real);
}

static boolean isRegularJarFile(Path p) {
    try {
        Path real = p.toRealPath();
        return Files.isRegularFile(real) && real.toString().endsWith(".jar");
    } catch (IOException e) {
        return false;
    }
}

try {
    JarFile jar = JarFileUtils.openJarFile(path);
} catch (IllegalArgumentException e) {
    if (String.valueOf(e.getMessage()).endsWith("not file")) {
        logger.warn("Skipping non-regular file: {}", path);
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling JarFileUtils.openJarFile(path) with a path that exists but is not a regular file — e.g. a device node, named pipe, unix socket, dangling symlink, or other special filesystem entry.

Common situations: Mount points or containers exposing device/socket files inside the scanned lib directory; broken symbolic links left by interrupted deployments or package managers; CI environments where build outputs were replaced by pipes (e.g. `unzip - | ...` mishaps).

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

• not found
• is directory
• defineAgentPackage fail: Caused by:
• ModuleSupportFactory() initialize fail
• MalformedURL error

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