apache/flink · error · ProgramInvocationException

Unknown I/O error while extracting contained jar files.

Error message

Unknown I/O error while extracting contained jar files.

What it means

A catch-all (Throwable) wrapping any failure during extractContainedLibraries. This method opens a JarFile and copies every contained nested jar to temp files; if anything in that process throws (IO, security, or otherwise), it is wrapped here. It is a broad safety net around the entire extraction routine.

Source

Thrown at flink-clients/src/main/java/org/apache/flink/client/program/PackagedProgram.java:558

                for (final JarEntry entry : containedJarFileEntries) {
                    // '/' as in case of zip, jar
                    // java.util.zip.ZipEntry#isDirectory always looks only for '/' not for
                    // File.separator
                    final String name = entry.getName().replace('/', '_');
                    final File tempFile = copyLibToTempFile(name, rnd, jar, entry, buffer);
                    extractedTempLibraries.add(tempFile);
                }

                incomplete = false;
            } finally {
                if (incomplete) {
                    deleteExtractedLibraries(extractedTempLibraries);
                }
            }

            return extractedTempLibraries;
        } catch (Throwable t) {
            throw new ProgramInvocationException(
                    "Unknown I/O error while extracting contained jar files.", t);
        }
    }

    private static File copyLibToTempFile(
            String name, Random rnd, JarFile jar, JarEntry input, byte[] buffer)
            throws ProgramInvocationException {
        final File output = createTempFile(rnd, input, name);
        try (final OutputStream out = new FileOutputStream(output);
                final InputStream in = new BufferedInputStream(jar.getInputStream(input))) {
            int numRead = 0;
            while ((numRead = in.read(buffer)) != -1) {
                out.write(buffer, 0, numRead);
            }
            return output;
        } catch (IOException e) {
            throw new ProgramInvocationException(
                    "An I/O error occurred while extracting nested library '"

View on GitHub (pinned to 2f3c205e92)

Solutions

Verify the jar is a valid zip: 'unzip -t your.jar'.
Check that the system temp directory (java.io.tmpdir) is writable and has space.
If running in a container, ensure /tmp is mounted as writable storage.
Re-download or re-build the jar to rule out corruption.

Defensive patterns

Strategy: try-catch

Validate before calling

if (!jarFile.exists() || !jarFile.isFile()) {
    throw new IllegalArgumentException("Jar does not exist: " + jarFile);
}
File tmpDir = new File(System.getProperty("java.io.tmpdir"));
if (!tmpDir.canWrite()) {
    throw new IllegalStateException("Temp dir not writable: " + tmpDir);
}

Try / catch

try {
    List<File> libs = PackagedProgram.extractContainedLibraries(jarUrl);
} catch (ProgramInvocationException e) {
    // inspect cause for corrupt jar / disk full / permissions
    throw e;
}

Prevention

Validate jar integrity with 'unzip -t' before deployment.
Ensure java.io.tmpdir is writable and has adequate free space.
Use complete, uncorrupted jar distributions.

When it happens

Trigger: Calling PackagedProgram.extractContainedLibraries(jarUrl) when the jar is corrupt, unreadable, the temp directory is full, or a security manager blocks file access. Also triggered if new JarFile(toURI) fails because the URL cannot be converted back to a file path.

Common situations: Corrupt or truncated jar (failed upload/download), jar on a network filesystem that becomes unavailable, /tmp full or read-only in a container, or security manager restrictions.

Related errors

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/fb643ec726028fdc. Report an issue: GitHub.