SonarSource/sonarqube · error · IllegalStateException

Failed to create directory %s

Error message

Failed to create directory %s

What it means

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).

Source

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

      throw new IllegalStateException("Can not zip directory " + dir + " to file " + toFile, e);
    }
  }

  /**
   * Creates specified directory if it does not exist yet and any non existing parent.
   *
   * @throws IllegalStateException if specified File exists but is not a directory
   * @throws IllegalStateException if directory creation failed
   */
  public void createDir(File dir) {
    Path dirPath = requireNonNull(dir, "dir can not be null").toPath();
    if (dirPath.toFile().exists()) {
      checkState(dirPath.toFile().isDirectory(), "%s is not a directory", dirPath);
    } else {
      try {
        createDirectories(dirPath);
      } catch (IOException e) {
        throw new IllegalStateException(format("Failed to create directory %s", dirPath), e);
      }
    }
  }

  private static void checkOrThrowIOE(boolean expression, @Nullable String errorMessageTemplate, @Nullable Object... errorMessageArgs) throws IOException {
    if (!expression) {
      throw new IOException(format(errorMessageTemplate, errorMessageArgs));
    }
  }
}

View on GitHub (pinned to 184c821202)

Solutions

1. Check parent directory permissions for the process user
2. Ensure no file exists where a directory is needed
3. Verify the filesystem is writable and not full
4. Run as a user with rights over the path, or pre-create the directory

Example fix

// before
files2.createDir(Paths.get(unknownRoot, "work"));
// after
Path dir = Paths.get(knownWritableRoot, "work");
Files.createDirectories(dir.getParent());
files2.createDir(dir);

Path parent = dirPath.toAbsolutePath().getParent();
if (dirPath.toFile().exists() && !dirPath.toFile().isDirectory()) {
  throw new IllegalArgumentException("Path exists and is not a directory: " + dirPath);
}
if (parent != null && !parent.toFile().canWrite()) {
  throw new IllegalArgumentException("Parent not writable: " + parent);
}

boolean canCreateDir(Path p) {
  File f = p.toFile();
  return !f.exists() || f.isDirectory();
}

try {
  files2.createDir(dirPath);
} catch (IllegalStateException e) {
  LOGGER.error("Cannot create dir {}", dirPath, e.getCause());
  throw new IOException("Directory setup failed", e);
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• Directory '%s' is a file
• '%s' is not a directory
• Can not write to file
• Can not delete
• Can not move file to

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