SonarSource/sonarqube · error · IllegalStateException

Can not unzip file ${zipFile} to directory ${toDir}

Error message

Can not unzip file ${zipFile} to directory ${toDir}

What it means

Files2.unzipToDir wraps any IOException from unzipping an archive into an IllegalStateException, since in the compute-engine task context a failed unzip is unrecoverable. It means the zip file could not be read or its entries extracted to the target directory. The original IOException is preserved as the cause.

Source

Thrown at server/sonar-ce-task-projectanalysis/src/main/java/org/sonar/ce/task/util/Files2.java:240

   */
  public void unzipToDirOrThrowIOE(File zipFile, File toDir) throws IOException {
    checkOrThrowIOE(!zipFile.isDirectory(), "File %s exists but is a directory", zipFile);
    checkOrThrowIOE(zipFile.exists(), "File %s does not exist", zipFile);
    ZipUtils.unzip(zipFile, toDir);
  }

  /**
   * Unzips a file to the specified directory. The directory is created if it does not exist.
   *
   * @throws IllegalStateException if {@code zipFile} is a directory
   * @throws IllegalStateException if {@code zipFile} does not exist
   * @throws IllegalStateException if {@code toDir} can not be created
   */
  public void unzipToDir(File zipFile, File toDir) {
    try {
      unzipToDirOrThrowIOE(zipFile, toDir);
    } catch (IOException e) {
      throw new IllegalStateException("Can not unzip file " + zipFile + " to directory " + toDir, e);
    }
  }

  /**
   * Zips the directory {@code dir} to the file {@code toFile}. If {@code toFile} is overridden
   * if it exists, else it is created.
   *
   * @throws IllegalStateException if {@code dir} is a not directory
   * @throws IllegalStateException if {@code dir} does not exist
   * @throws IllegalStateException if {@code toFile} can not be created
   */
  public void zipDirOrThrowIOE(File dir, File toFile) throws IOException {
    checkOrThrowIOE(dir.exists(), "Directory %s does not exist", dir);
    checkOrThrowIOE(dir.isDirectory(), "File %s exists but is not a directory", dir);
    ZipUtils.zipDir(dir, toFile);
  }

  /**

View on GitHub (pinned to 184c821202)

Solutions

1. Verify the zip file exists, is non-empty and readable by the CE process user
2. Check the target directory can be created/written (permissions, disk space)
3. Regenerate or re-download the zip file if corrupt
4. Check the cause IOException in the stack trace for the underlying reason

Example fix

// before
files2.unzipToDir(zipFile, toDir);
// after
if (!zipFile.isFile() || !zipFile.canRead()) {
  throw new IllegalStateException("Zip file missing or unreadable: " + zipFile);
}
files2.unzipToDir(zipFile, toDir);

if (!zipFile.isFile() || !zipFile.canRead() || zipFile.length() == 0) {
  throw new IllegalArgumentException("Zip file missing, unreadable or empty: " + zipFile);
}
if (toDir.exists() && !toDir.isDirectory()) {
  throw new IllegalArgumentException("Target exists and is not a directory: " + toDir);
}

boolean isReadableZip(File f) {
  return f != null && f.isFile() && f.canRead() && f.length() > 0;
}

try {
  files2.unzipToDir(zipFile, toDir);
} catch (IllegalStateException e) {
  LOGGER.error("Unzip failed for {}", zipFile, e.getCause());
  // cleanup partial toDir, fail task or fall back
}

When it happens

Trigger: Calling unzipToDir(zipFile, toDir) when the zip file is missing/corrupt/truncated, unreadable (permissions), or when toDir cannot be created or written.

Common situations: Worker telemetry/report directories on disk full or with wrong permissions; partially downloaded or corrupted zip files; toDir path occupied by a regular file.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Can not zip directory ${dir} to file ${toFile}
• Can not write to file
• Can not delete
• Can not move file to
• Directory could not be created

AI-assisted analysis of SonarSource/sonarqube@184c821202 (2026-09-09). Data as JSON: /api/errors/0955b1098559a3a7. Report an issue: GitHub.