apache/druid · error · IllegalStateException

Failed to create temporary directory in path [%s]

Error message

Failed to create temporary directory in path [%s]

What it means

FileUtils.createTempDirInLocation throws this ISE with the IOException attached when creating a temp directory fails for a reason other than a missing parent, read-only filesystem, or access denial. It is the catch-all branch of the temp-directory creation error handling and preserves the original cause for diagnosis.

Source

Thrown at processing/src/main/java/org/apache/druid/java/util/common/FileUtils.java:493

  public static File createTempDirInLocation(final Path parentDirectory, @Nullable final String prefix)
  {
    try {
      final Path tmpPath = Files.createTempDirectory(
          parentDirectory,
          prefix == null || prefix.isEmpty() ? "druid" : prefix
      );
      return tmpPath.toFile();
    }
    catch (IOException e) {
      // Some inspection to improve error messages.
      if (e instanceof NoSuchFileException && !parentDirectory.toFile().exists()) {
        throw new ISE("Path [%s] does not exist", parentDirectory);
      } else if ((e instanceof FileSystemException && e.getMessage().contains("Read-only file system"))
                 || (e instanceof AccessDeniedException)) {
        throw new ISE("Path [%s] is not writable, check permissions", parentDirectory);
      } else {
        // Well, maybe it was something else.
        throw new ISE(e, "Failed to create temporary directory in path [%s]", parentDirectory);
      }
    }
  }

  /**
   * Create "directory" and all intermediate directories as needed. If the directory is successfully created, or already
   * exists, returns quietly. Otherwise, throws an IOException.
   *
   * Simpler to use than {@link File#mkdirs()}, and more reliable since it is safe from races where two threads try
   * to create the same directory at the same time.
   *
   * The name is inspired by UNIX {@code mkdir -p}, which has the same behavior.
   */
  @SuppressForbidden(reason = "File#mkdirs")
  public static void mkdirp(final File directory) throws IOException
  {
    // isDirectory check after mkdirs is necessary in case of concurrent calls to mkdirp, because two concurrent
    // calls to mkdirs cannot both succeed.

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Read the attached cause (ISE wraps the IOException) to see the real filesystem error
2. Check whether the parent path is a regular file instead of a directory; remove or rename it
3. Check disk space and inode availability (df -h, df -i) on the target filesystem
4. Point the temp-dir setting at a different, healthy filesystem
5. If the message hints at path length, use a shorter base path

Example fix

// before
File tmp = FileUtils.createTempDir(new File("/data/persist")); // /data/persist is a file
// after
// remove the stray file and ensure /data/persist is a directory
new File("/data/persist").delete();
Files.createDirectories(Paths.get("/data/persist"));
File tmp = FileUtils.createTempDir(new File("/data/persist"));

File parent = new File(path);
if (!parent.exists()) Files.createDirectories(parent.toPath());
if (!parent.isDirectory()) throw new IllegalStateException("Parent is not a directory: " + path);
if (!parent.canWrite()) throw new IllegalStateException("Parent not writable: " + path);

static boolean isValidTempParent(File dir) {
  return dir != null && dir.isDirectory() && dir.canWrite();
}

try {
  File tmp = FileUtils.createTempDir(parent);
} catch (ISE e) {
  throw new RuntimeException("Temp dir creation failed in " + parent + ": " + e.getCause(), e);
}

When it happens

Trigger: Calling FileUtils.createTempDir/createTempDirInLocation when the underlying atomic directory creation throws an IOException not classified as NoSuchFileException, AccessDeniedException, or read-only FileSystemException (e.g. device full in a way surfaced differently, I/O errors, path exists as a file, name too long).

Common situations: Parent path exists but is a regular file, not a directory; filesystem errors or corruption; exceeding filename/path length limits; out of inodes or disk-full conditions; exotic filesystems rejecting atomic mkdir.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Cannot list directory [%s]
• Could not close channel for level [%d] and rank [%d]
• Unable to close channel for name :
• Path [%s] does not exist
• Path [%s] is not writable, check permissions

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/242f6fca10701325. Report an issue: GitHub.