{"record":{"id":"99a7b766e010d500","repo":"elastic/elasticsearch","slug":"config-99a7b7","errorCode":"CONFIG","errorMessage":"Temporary directory [${path}] does not exist or is not accessible","messagePattern":"Temporary directory \\[(.+?)\\] does not exist or is not accessible","errorType":"error_code","errorClass":"UserException","httpStatus":null,"severity":"error","filePath":"distribution/tools/server-cli/src/main/java/org/elasticsearch/server/cli/ServerProcessUtils.java","lineNumber":38,"sourceCode":"import java.nio.file.Path;\nimport java.nio.file.Paths;\nimport java.nio.file.attribute.FileAttribute;\n\npublic class ServerProcessUtils {\n\n    /**\n     * Returns the java.io.tmpdir Elasticsearch should use, creating it if necessary.\n     *\n     * <p> On non-Windows OS, this will be created as a subdirectory of the default temporary directory.\n     * Note that this causes the created temporary directory to be a private temporary directory.\n     */\n    public static Path setupTempDir(ProcessInfo processInfo) throws UserException {\n        final Path path;\n        String tmpDirOverride = processInfo.envVars().get(\"ES_TMPDIR\");\n        if (tmpDirOverride != null) {\n            path = Paths.get(tmpDirOverride);\n            if (Files.exists(path) == false) {\n                throw new UserException(ExitCodes.CONFIG, \"Temporary directory [\" + path + \"] does not exist or is not accessible\");\n            }\n            if (Files.isDirectory(path) == false) {\n                throw new UserException(ExitCodes.CONFIG, \"Temporary directory [\" + path + \"] is not a directory\");\n            }\n        } else {\n            try {\n                if (processInfo.sysprops().get(\"os.name\").startsWith(\"Windows\")) {\n                    /*\n                     * On Windows, we avoid creating a unique temporary directory per invocation lest\n                     * we pollute the temporary directory. On other operating systems, temporary directories\n                     * will be cleaned automatically via various mechanisms (e.g., systemd, or restarts).\n                     */\n                    path = Paths.get(processInfo.sysprops().get(\"java.io.tmpdir\"), \"elasticsearch\");\n                    Files.createDirectories(path);\n                } else {\n                    path = createTempDirectory(\"elasticsearch-\");\n                }\n            } catch (IOException e) {","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/distribution/tools/server-cli/src/main/java/org/elasticsearch/server/cli/ServerProcessUtils.java#L20-L56","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nexport ES_TMPDIR=/opt/es-tmp  # path missing\nbin/elasticsearch\n# after\nmkdir -p /opt/es-tmp && chown elasticsearch:elasticsearch /opt/es-tmp\nexport ES_TMPDIR=/opt/es-tmp\nbin/elasticsearch","handlingStrategy":"validation","validationCode":"String tmp = System.getenv(\"ES_TMPDIR\");\nif (tmp != null && !Files.isDirectory(Paths.get(tmp))) {\n    throw new IllegalStateException(\"ES_TMPDIR=\" + tmp + \" does not exist; create it before starting Elasticsearch.\");\n}","typeGuard":"static boolean isUsableTmpDir(String path) {\n    return path != null && Files.isDirectory(Paths.get(path));\n}","tryCatchPattern":"try {\n    Path p = ServerProcessUtils.setupTempDir(processInfo);\n} catch (UserException e) {\n    if (e.exitCode == ExitCodes.CONFIG && e.getMessage().contains(\"does not exist\")) {\n        // create the directory and retry once\n        Files.createDirectories(Paths.get(System.getenv(\"ES_TMPDIR\")));\n    } else {\n        throw e;\n    }\n}","preventionTips":["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."],"tags":["cli","tmpdir","filesystem","startup","environment","configuration"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T08:17:17.861Z"}