apache/druid · error · IllegalStateException

System property java.io.tmpdir is not set, cannot create tem

Error message

System property java.io.tmpdir is not set, cannot create temporary directories

What it means

FileUtils.getTempDir() reads the java.io.tmpdir system property to find where temporary directories are created. If the property is not set (never expected on a normal JVM), it throws IllegalStateException because Druid cannot know where to put temp files.

Source

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

   * Creates a temporary directory inside the configured temporary space (java.io.tmpdir). Similar to the method
   * {@link com.google.common.io.Files#createTempDir()} from Guava, but has nicer error messages.
   *
   * @param prefix base directory name; if null/empty then this method will use "druid"
   *
   * @throws IllegalStateException if the directory could not be created
   */
  public static File createTempDir(@Nullable final String prefix)
  {
    return createTempDirInLocation(getTempDir(), prefix);
  }

  public static Path getTempDir()
  {
    final String parentDirectory = System.getProperty("java.io.tmpdir");

    if (parentDirectory == null) {
      // Not expected.
      throw new ISE("System property java.io.tmpdir is not set, cannot create temporary directories");
    }
    return new File(parentDirectory).toPath();
  }

  /**
   * Resolves {@code path} below {@code directory}, rejecting absolute paths and parent traversal that would escape it.
   * This is intended for paths containing externally supplied identifiers.
   */
  public static File resolveFileWithinDirectory(final File directory, final String path)
  {
    final Path normalizedDirectory = directory.toPath().toAbsolutePath().normalize();
    final Path childPath;
    try {
      childPath = Path.of(path);
    }
    catch (InvalidPathException e) {
      throw new IAE(e, "Path[%s] is not within directory[%s]", path, directory);
    }

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Ensure java.io.tmpdir is set: launch with -Djava.io.tmpdir=/path/to/tmp
2. Verify with System.out.println(System.getProperty("java.io.tmpdir")) in the failing environment
3. If embedding Druid, initialize the property programmatically before calling createTempDir: System.setProperty("java.io.tmpdir", ...)
4. Check that launch wrappers/agents are not clearing system properties

Example fix

// before launch
java -jar druid.jar
// after launch
java -Djava.io.tmpdir=/var/tmp -jar druid.jar

if (System.getProperty("java.io.tmpdir") == null) {
  System.setProperty("java.io.tmpdir", "/tmp");
}

try {
  File tmp = FileUtils.createTempDir();
} catch (IllegalStateException e) {
  System.setProperty("java.io.tmpdir", System.getenv().getOrDefault("TMPDIR", "/tmp"));
  tmp = FileUtils.createTempDir();
}

When it happens

Trigger: Calling getTempDir()/createTempDir() in a JVM where the java.io.tmpdir system property is null — e.g. a JVM launched with -Djava.io.tmpdir= cleared, custom/embedded JVM setups, or environments that strip system properties.

Common situations: Embedded Druid in application servers or test harnesses that sanitize System properties; misconfigured launch scripts setting java.io.tmpdir to empty and the property resolving unexpectedly.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Path [%s] does not exist
• The gRPC query server requires either a Basic or Anonymous a
• Metric [%s] not whitelisted.
• Can't load TrustStore. Truststore path or password is not se
• druid.request.logging.transportUrl must be set when transpor

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