jenkinsci/jenkins · error · IOException

Failed to unpack %s (%d bytes read)

Error message

Failed to unpack %s (%d bytes read)

What it means

Thrown inside the Unpack MasterToSlaveFileCallable when unpacking a stream opened directly from a URL on the agent side fails. Unlike the controller-side variant it reports only bytes read (no Content-Length) because openStream() provides no length. Runs remotely via act(); failure bubbles up to install's retry/fallback.

Source

Thrown at core/src/main/java/hudson/FilePath.java:1114

    // this reads from arbitrary URL
    private static final class Unpack extends MasterToSlaveFileCallable<Void> {
        private final URL archive;

        Unpack(URL archive) {
            this.archive = archive;
        }

        @Override public Void invoke(File dir, VirtualChannel channel) throws IOException, InterruptedException {
            try (InputStream in = archive.openStream()) {
                CountingInputStream cis = new CountingInputStream(in);
                try {
                    if (archive.toExternalForm().endsWith(".zip")) {
                        unzip(dir, cis);
                    } else {
                        readFromTar("input stream", dir, TarCompression.GZIP.extract(cis));
                    }
                } catch (IOException x) {
                    throw new IOException(String.format("Failed to unpack %s (%d bytes read)", archive, cis.getByteCount()), x);
                }
            }
            return null;
        }
    }

    /**
     * Reads the URL on the current VM, and streams the data to this file using the Remoting channel.
     * <p>This is different from resolving URL remotely.
     * If you instead wished to open an HTTP(S) URL on the remote side,
     * prefer <a href="http://javadoc.jenkins.io/plugin/apache-httpcomponents-client-4-api/io/jenkins/plugins/httpclient/RobustHTTPClient.html#copyFromRemotely-hudson.FilePath-java.net.URL-hudson.model.TaskListener-">{@code RobustHTTPClient.copyFromRemotely}</a>.
     * @since 1.293
     */
    public void copyFrom(URL url) throws IOException, InterruptedException {
        try (InputStream in = url.openStream()) {
            copyFrom(in);
        }
    }

View on GitHub (pinned to 2e228ff40b)

Solutions

1. Check the agent can reach the URL (network/firewall) and has disk space.
2. Rely on the controller-side fallback if the agent fetch consistently fails (it will retry from controller).
3. Validate the archive integrity at the source.
4. Ensure agent java.io.tmpdir is writable and not full.

Example fix

null

null

null

try {
    fp.act(new Unpack(archive));
} catch (IOException e) {
    if (e.getMessage().startsWith("Failed to unpack")) {
        // agent-side fetch failed — fall back to controller-side download
    } else throw e;
}

When it happens

Trigger: archive.openStream() yields a truncated or corrupt stream on the agent; agent cannot reach the URL (network/firewall); gzip/zip parse error mid-stream; agent disk full during write.

Common situations: Agent in a restricted network cannot fetch the URL directly (triggers fallback to controller download); archive served behind auth the agent lacks; agent tmp disk full.

Related errors

• Failed to unpack %s (%d bytes read of total %d)
• remote file operation failed
• Failed to join the process
• Failed to expand {}
• Zip ${zipFile.getPath()} contains illegal file name that bre

AI-assisted analysis of jenkinsci/jenkins@2e228ff40b (2026-08-14). Data as JSON: /api/errors/f4f0180bdd9906bb. Report an issue: GitHub.