{"record":{"id":"310c1632632282d8","repo":"SonarSource/sonarqube","slug":"failed-to-create-directory-s","errorCode":null,"errorMessage":"Failed to create directory %s","messagePattern":"Failed to create 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":288,"sourceCode":"      throw new IllegalStateException(\"Can not zip directory \" + dir + \" to file \" + toFile, e);\n    }\n  }\n\n  /**\n   * Creates specified directory if it does not exist yet and any non existing parent.\n   *\n   * @throws IllegalStateException if specified File exists but is not a directory\n   * @throws IllegalStateException if directory creation failed\n   */\n  public void createDir(File dir) {\n    Path dirPath = requireNonNull(dir, \"dir can not be null\").toPath();\n    if (dirPath.toFile().exists()) {\n      checkState(dirPath.toFile().isDirectory(), \"%s is not a directory\", dirPath);\n    } else {\n      try {\n        createDirectories(dirPath);\n      } catch (IOException e) {\n        throw new IllegalStateException(format(\"Failed to create directory %s\", dirPath), e);\n      }\n    }\n  }\n\n  private static void checkOrThrowIOE(boolean expression, @Nullable String errorMessageTemplate, @Nullable Object... errorMessageArgs) throws IOException {\n    if (!expression) {\n      throw new IOException(format(errorMessageTemplate, errorMessageArgs));\n    }\n  }\n}\n","sourceCodeStart":270,"sourceCodeEnd":299,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-ce-task-projectanalysis/src/main/java/org/sonar/ce/task/util/Files2.java#L270-L299","documentation":"Files2.createDir throws IllegalStateException when java.nio Files.createDirectories fails, converting the checked IOException into an unchecked one. It means a required directory could not be created (or the existing path is not a directory, which triggers a separate checkState message).","triggerScenarios":"Calling createDir(path) when a parent path component exists as a regular file, the user lacks write permission on the parent, or the filesystem is full/read-only.","commonSituations":"CE workspace/home directories on read-only mounts or with root-owned parents; path conflicts after upgrades; Docker containers running as non-root user without volume permissions.","solutions":["Check parent directory permissions for the process user","Ensure no file exists where a directory is needed","Verify the filesystem is writable and not full","Run as a user with rights over the path, or pre-create the directory"],"exampleFix":"// before\nfiles2.createDir(Paths.get(unknownRoot, \"work\"));\n// after\nPath dir = Paths.get(knownWritableRoot, \"work\");\nFiles.createDirectories(dir.getParent());\nfiles2.createDir(dir);","handlingStrategy":"try-catch","validationCode":"Path parent = dirPath.toAbsolutePath().getParent();\nif (dirPath.toFile().exists() && !dirPath.toFile().isDirectory()) {\n  throw new IllegalArgumentException(\"Path exists and is not a directory: \" + dirPath);\n}\nif (parent != null && !parent.toFile().canWrite()) {\n  throw new IllegalArgumentException(\"Parent not writable: \" + parent);\n}","typeGuard":"boolean canCreateDir(Path p) {\n  File f = p.toFile();\n  return !f.exists() || f.isDirectory();\n}","tryCatchPattern":"try {\n  files2.createDir(dirPath);\n} catch (IllegalStateException e) {\n  LOGGER.error(\"Cannot create dir {}\", dirPath, e.getCause());\n  throw new IOException(\"Directory setup failed\", e);\n}","preventionTips":["Pre-create parent directories with correct ownership","Avoid placing files where directories are expected","Verify container/volume permissions when running as non-root","Check mounts are not read-only"],"tags":["io","directory","filesystem"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}