{"record":{"id":"0955b1098559a3a7","repo":"SonarSource/sonarqube","slug":"can-not-unzip-file-zipfile-to-directory-todir","errorCode":null,"errorMessage":"Can not unzip file ${zipFile} to directory ${toDir}","messagePattern":"Can not unzip file (.+?) to directory (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"server/sonar-ce-task-projectanalysis/src/main/java/org/sonar/ce/task/util/Files2.java","lineNumber":240,"sourceCode":"   */\n  public void unzipToDirOrThrowIOE(File zipFile, File toDir) throws IOException {\n    checkOrThrowIOE(!zipFile.isDirectory(), \"File %s exists but is a directory\", zipFile);\n    checkOrThrowIOE(zipFile.exists(), \"File %s does not exist\", zipFile);\n    ZipUtils.unzip(zipFile, toDir);\n  }\n\n  /**\n   * Unzips a file to the specified directory. The directory is created if it does not exist.\n   *\n   * @throws IllegalStateException if {@code zipFile} is a directory\n   * @throws IllegalStateException if {@code zipFile} does not exist\n   * @throws IllegalStateException if {@code toDir} can not be created\n   */\n  public void unzipToDir(File zipFile, File toDir) {\n    try {\n      unzipToDirOrThrowIOE(zipFile, toDir);\n    } catch (IOException e) {\n      throw new IllegalStateException(\"Can not unzip file \" + zipFile + \" to directory \" + toDir, e);\n    }\n  }\n\n  /**\n   * Zips the directory {@code dir} to the file {@code toFile}. If {@code toFile} is overridden\n   * if it exists, else it is created.\n   *\n   * @throws IllegalStateException if {@code dir} is a not directory\n   * @throws IllegalStateException if {@code dir} does not exist\n   * @throws IllegalStateException if {@code toFile} can not be created\n   */\n  public void zipDirOrThrowIOE(File dir, File toFile) throws IOException {\n    checkOrThrowIOE(dir.exists(), \"Directory %s does not exist\", dir);\n    checkOrThrowIOE(dir.isDirectory(), \"File %s exists but is not a directory\", dir);\n    ZipUtils.zipDir(dir, toFile);\n  }\n\n  /**","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-ce-task-projectanalysis/src/main/java/org/sonar/ce/task/util/Files2.java#L222-L258","documentation":"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.","triggerScenarios":"Calling unzipToDir(zipFile, toDir) when the zip file is missing/corrupt/truncated, unreadable (permissions), or when toDir cannot be created or written.","commonSituations":"Worker telemetry/report directories on disk full or with wrong permissions; partially downloaded or corrupted zip files; toDir path occupied by a regular file.","solutions":["Verify the zip file exists, is non-empty and readable by the CE process user","Check the target directory can be created/written (permissions, disk space)","Regenerate or re-download the zip file if corrupt","Check the cause IOException in the stack trace for the underlying reason"],"exampleFix":"// before\nfiles2.unzipToDir(zipFile, toDir);\n// after\nif (!zipFile.isFile() || !zipFile.canRead()) {\n  throw new IllegalStateException(\"Zip file missing or unreadable: \" + zipFile);\n}\nfiles2.unzipToDir(zipFile, toDir);","handlingStrategy":"try-catch","validationCode":"if (!zipFile.isFile() || !zipFile.canRead() || zipFile.length() == 0) {\n  throw new IllegalArgumentException(\"Zip file missing, unreadable or empty: \" + zipFile);\n}\nif (toDir.exists() && !toDir.isDirectory()) {\n  throw new IllegalArgumentException(\"Target exists and is not a directory: \" + toDir);\n}","typeGuard":"boolean isReadableZip(File f) {\n  return f != null && f.isFile() && f.canRead() && f.length() > 0;\n}","tryCatchPattern":"try {\n  files2.unzipToDir(zipFile, toDir);\n} catch (IllegalStateException e) {\n  LOGGER.error(\"Unzip failed for {}\", zipFile, e.getCause());\n  // cleanup partial toDir, fail task or fall back\n}","preventionTips":["Check file existence/readability before unzipping","Monitor disk space on the workspace volume","Validate zip integrity (checksum) after download/transfer","Run the process as a user with write access to the target directory"],"tags":["io","zip","filesystem"],"backgroundTag":"file-read-failed","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}