elastic/elasticsearch · error · UncheckedIOException

Failed to unpack {} with checksum {}

Error message

Failed to unpack {} with checksum {}

What it means

UnpackTransform throws an UncheckedIOException wrapping the IOException from `unpack(...)` when extracting an archive (tar/zip) fails. Before throwing it computes a SHA-1 hash of the archive file (logging a warning if that also fails) and includes the archive name + hash in the message, so the exact failing artifact is identifiable in a dependency graph.

Source

Thrown at build-tools/src/main/java/org/elasticsearch/gradle/transform/UnpackTransform.java:100

    default void transform(TransformOutputs outputs) {
        File archiveFile = getArchiveFile().get().getAsFile();
        File extractedDir = outputs.dir(archiveFile.getName());

        if (getParameters().getIncludeArtifactName().getOrElse(false)) {
            extractedDir = new File(extractedDir, archiveFile.getName());
        }

        try {
            LOGGER.info("Unpacking {} using {}.", archiveFile.getName(), getClass().getSimpleName());
            unpack(archiveFile, extractedDir, outputs, getParameters().getAsFiletreeOutput());
        } catch (IOException e1) {
            String hash = "[unknown]";
            try {
                hash = getSha1(archiveFile);
            } catch (Exception e2) {
                LOGGER.warn("Unable to calculate hash for file " + archiveFile.getPath(), e2);
            }
            throw new UncheckedIOException("Failed to unpack " + archiveFile.getName() + " with checksum " + hash, e1);
        }
    }

    void unpack(File archiveFile, File targetDir, TransformOutputs outputs, boolean asFiletreeOutput) throws IOException;

    default Function<String, Path> pathResolver() {
        List<String> keepPatterns = getParameters().getKeepStructureFor();
        String trimmedPrefixPattern = getParameters().getTrimmedPrefixPattern();
        return trimmedPrefixPattern != null ? (i) -> trimArchiveExtractPath(keepPatterns, trimmedPrefixPattern, i) : (i) -> Path.of(i);
    }

    /*
     * We want to be able to trim off certain prefixes when transforming archives.
     *
     * E.g We want to remove up to the and including the jdk-.* relative paths. That is a JDK archive is structured as:
     *   jdk-12.0.1/
     *   jdk-12.0.1/Contents
     *   ...

View on GitHub (pinned to db6a809a66)

Solutions

1. Verify the archive integrity: compare the printed SHA-1 against the published checksum, or re-download with `--refresh-dependencies`.
2. Clear the transform cache for that input (`./gradlew --rerun-tasks` or remove the specific transform output dir).
3. Confirm the unpack implementation matches the archive type (the abstract `unpack(...)` is implemented per format — check the concrete subclass used).
4. Check disk space and that the output directory is writable.

// Verify archive integrity before relying on the transform
String expected = publishedSha1(archiveFile.getName());
String actual = sha1Of(archiveFile);
if (!expected.equals(actual)) {
  throw new IllegalStateException("Corrupt archive " + archiveFile + "; re-download.");
}

try {
  unpackTransform();
} catch (UncheckedIOException e) {
  if (e.getMessage().contains("Failed to unpack")) {
    // the message includes the sha1 — compare to the published checksum, then refresh deps
  }
  throw e;
}

When it happens

Trigger: A registered UnpackTransform (tar/zip extraction to a directory) fails because the archive is corrupt, truncated, of an unexpected format, password-protected, or the output directory can't be written.

Common situations: Corrupt or partially downloaded dependency archive; format mismatch (e.g. a `.tar.gz` declared as `.zip` or vice versa); disk full; the archive's checksum in the message lets you verify integrity against the published artifact.

Related errors

• Failed to patch archive
• Unable to create reaper JAR output directory {}
• Cannot create directory '%s' as it already exists, but is no
• Cannot create parent directory '%s' when creating directory
• Failed to create parent directory '%s' when creating directo

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/113941f470729423. Report an issue: GitHub.