elastic/elasticsearch · error · UserException

CONFIG

CONFIG

Error message

Temporary directory [${path}] does not exist or is not accessible

What it means

Thrown by ServerProcessUtils.setupTempDir when the ES_TMPDIR environment variable is set but the path it points to does not exist on the filesystem. Elasticsearch uses ES_TMPDIR for performance temp files, JVM performance counters, and short-lived artifacts, and when it is explicitly set the code refuses to create it (treating it as an operator-controlled path). The check exits with code CONFIG because this is an environment misconfiguration, not a usage error.

Source

Thrown at distribution/tools/server-cli/src/main/java/org/elasticsearch/server/cli/ServerProcessUtils.java:38

import java.nio.file.Path;
import java.nio.file.Paths;
import java.nio.file.attribute.FileAttribute;

public class ServerProcessUtils {

    /**
     * Returns the java.io.tmpdir Elasticsearch should use, creating it if necessary.
     *
     * <p> On non-Windows OS, this will be created as a subdirectory of the default temporary directory.
     * Note that this causes the created temporary directory to be a private temporary directory.
     */
    public static Path setupTempDir(ProcessInfo processInfo) throws UserException {
        final Path path;
        String tmpDirOverride = processInfo.envVars().get("ES_TMPDIR");
        if (tmpDirOverride != null) {
            path = Paths.get(tmpDirOverride);
            if (Files.exists(path) == false) {
                throw new UserException(ExitCodes.CONFIG, "Temporary directory [" + path + "] does not exist or is not accessible");
            }
            if (Files.isDirectory(path) == false) {
                throw new UserException(ExitCodes.CONFIG, "Temporary directory [" + path + "] is not a directory");
            }
        } else {
            try {
                if (processInfo.sysprops().get("os.name").startsWith("Windows")) {
                    /*
                     * On Windows, we avoid creating a unique temporary directory per invocation lest
                     * we pollute the temporary directory. On other operating systems, temporary directories
                     * will be cleaned automatically via various mechanisms (e.g., systemd, or restarts).
                     */
                    path = Paths.get(processInfo.sysprops().get("java.io.tmpdir"), "elasticsearch");
                    Files.createDirectories(path);
                } else {
                    path = createTempDirectory("elasticsearch-");
                }
            } catch (IOException e) {

View on GitHub (pinned to db6a809a66)

Solutions

Verify the path exists: `ls -ld $ES_TMPDIR`.
Create it with correct ownership: `mkdir -p $ES_TMPDIR && chown elasticsearch:elasticsearch $ES_TMPDIR`.
Ensure your systemd unit or Docker entrypoint creates ES_TMPDIR before starting Elasticsearch.
If you did not intend to override, unset ES_TMPDIR to let Elasticsearch create a private temp subdir under java.io.tmpdir.

Example fix

# before
export ES_TMPDIR=/opt/es-tmp  # path missing
bin/elasticsearch
# after
mkdir -p /opt/es-tmp && chown elasticsearch:elasticsearch /opt/es-tmp
export ES_TMPDIR=/opt/es-tmp
bin/elasticsearch

Defensive patterns

Strategy: validation

Validate before calling

String tmp = System.getenv("ES_TMPDIR");
if (tmp != null && !Files.isDirectory(Paths.get(tmp))) {
    throw new IllegalStateException("ES_TMPDIR=" + tmp + " does not exist; create it before starting Elasticsearch.");
}

Type guard

static boolean isUsableTmpDir(String path) {
    return path != null && Files.isDirectory(Paths.get(path));
}

Try / catch

try {
    Path p = ServerProcessUtils.setupTempDir(processInfo);
} catch (UserException e) {
    if (e.exitCode == ExitCodes.CONFIG && e.getMessage().contains("does not exist")) {
        // create the directory and retry once
        Files.createDirectories(Paths.get(System.getenv("ES_TMPDIR")));
    } else {
        throw e;
    }
}

Prevention

In systemd units use `ExecStartPre=/usr/bin/install -d -o elasticsearch -g elasticsearch ${ES_TMPDIR}`.
In Docker, mount or create the tmpdir in the entrypoint before launching ES.
Add an env validation step to startup wrappers.

When it happens

Trigger: Exporting `ES_TMPDIR=/opt/es-tmp` where that directory was never created or was since removed. Mounting a tmpfs at ES_TMPDIR that failed to mount. Setting ES_TMPDIR to a path inside a container path that is not mounted in the running container.

Common situations: Packaging or systemd unit sets ES_TMPDIR but the directory creation step was skipped or reordered. NFS mount of the tmpdir failed silently. The directory was cleaned by tmpwatch/systemd-tmpfiles between runs.

Related errors

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/99a7b766e010d500. Report an issue: GitHub.