pinpoint-apm/pinpoint · error · IllegalStateException

create fail

Error message

${file} create fail

What it means

JarFileScanner's private constructor opens the target file as a JarFile; if the file cannot be opened as a jar (IOException), it wraps the failure in IllegalStateException with '<file> create fail'. The original IOException cause is swallowed.

Solutions

1. Verify the file exists and is readable, and is a valid zip/jar (unzip -t)
2. Restore or re-download the corrupted/missing jar
3. Check file permissions and that no other process holds an incompatible lock on the file
4. Wrap construction in try-catch for IllegalStateException since the underlying IOException is not propagated

Example fix

// before
File f = new File("/plugins/app.jar"); // truncated download
Scanner s = JarFileScanner.create(f);
// after
File f = new File("/plugins/app.jar");
if (f.isFile() && f.length() > 0 && f.canRead()) {
    Scanner s = JarFileScanner.create(f);
}

if (!file.isFile() || !file.canRead() || file.length() == 0) throw new IllegalStateException("invalid jar file: " + file);

try { scanner = JarFileScanner.create(jar); } catch (IllegalStateException e) { log.error("cannot open jar {}: {}", jar, e.getMessage()); }

When it happens

Trigger: Constructing a JarFileScanner over a file that is missing, unreadable, corrupt, not a zip/jar, or locked by another process.

Common situations: Agent pointing at a stale or partially-downloaded jar; plugin directories containing empty/corrupt files; permission problems on the jar path; scanning a directory-classpath entry that is not a jar.

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

• Failed to close JarFile:
• banner IO failed
• can read
• create fail Caused by:
• I/O error getting type provider definitions

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

Appendix: source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/instrument/scanner/JarFileScanner.java:50

    private final JarFile jarFile;


    public static JarFileScanner of(String path) {
        Objects.requireNonNull(path, "path");
        return new JarFileScanner(new File(path));
    }

    public static JarFileScanner of(Path path) {
        Objects.requireNonNull(path, "path");
        return new JarFileScanner(path.toFile());
    }

    private JarFileScanner(File file) {
        Objects.requireNonNull(file, "file");
        try {
            this.jarFile = new JarFile(file);
        } catch (IOException e) {
            throw new IllegalStateException(file + " create fail");
        }
    }

    @Override
    public boolean exist(String fileName) {
        final JarEntry jarEntry = jarFile.getJarEntry(fileName);
        return jarEntry != null;
    }


    @Override
    public InputStream openStream(String fileName) {
        final JarEntry jarEntry = jarFile.getJarEntry(fileName);
        if (jarEntry == null) {
            return null;
        }
        try {
            return jarFile.getInputStream(jarEntry);

View on GitHub (pinned to 744c3d3075)