pinpoint-apm/pinpoint · error · IllegalStateException

create fail Caused by:

Error message

 create fail Caused by:

What it means

Thrown by JarFileUtils.openJarFile when new JarFile(file) throws IOException even though the path passed the is-directory/is-file/is-readable checks. It wraps the underlying IOException (corrupt jar, wrong format, I/O failure) into an IllegalStateException with the path and cause message attached.

Source

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

    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. Read the wrapped cause in the exception message/stack trace to see the real IOException
  2. Validate the jar: run 'jar tf <file>' or 'unzip -t <file>' to test integrity
  3. Re-download/rebuild the corrupted jar and redeploy the agent
  4. Confirm the file is actually a jar (file <path> shows 'Zip archive'), not a misnamed text file

Example fix

// before
Path p = Paths.get("/agent/plugin/truncated.jar"); // corrupted download
JarFile jf = JarFileUtils.openJarFile(p); // IllegalStateException create fail
// after
// re-download/rebuild the jar, verify with: unzip -t /agent/plugin/truncated.jar
JarFile jf = JarFileUtils.openJarFile(p); // OK
Defensive patterns

Strategy: try-catch

Validate before calling

try (JarFile probe = new JarFile(path.toFile())) { /* valid zip */ } catch (IOException e) { throw new IllegalStateException("invalid jar: " + path, e); }

Type guard

boolean isValidZip(Path p) { try { new java.util.zip.ZipFile(p.toFile()).close(); return true; } catch (IOException e) { return false; } }

Try / catch

try { return JarFileUtils.openJarFile(path); } catch (IllegalStateException e) { log.error("jar open failed: {}", e.getMessage(), e.getCause()); throw e; }

Prevention

When it happens

Trigger: Calling openJarFile(Path) on a file that exists and is readable but is not a valid zip/jar (truncated download, text file renamed to .jar), or an actual transient I/O error while opening.

Common situations: Corrupted or partially-uploaded plugin jar in the agent dir; a non-jar file placed in the plugin directory; disk/IO errors; jars built with unsupported zip features.

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

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