elastic/elasticsearch · error · UncheckedIOException

Failed to create geoip tmp directory for project [{}]

Error message

Failed to create geoip tmp directory for project [{}]

What it means

Thrown by DatabaseNodeService.getDatabaseTmpDirectory when Files.createDirectories fails for the per-project geoip temp directory (geoipTmpDirectory, optionally suffixed by the project id). The IOException is wrapped in an UncheckedIOException, so it surfaces during database load/unpack on the ingest node and prevents that node from serving geoip lookups.

Source

Thrown at modules/ip-location/src/main/java/org/elasticsearch/ingest/geoip/DatabaseNodeService.java:982

     * form. Names without an install-token infix (including non-mmdb side files such as
     * {@code <dbName>_LICENSE.txt} and {@code .tmp} / {@code .tmp.retrieved} files) pass through unchanged,
     * so this is safe to apply to every entry in the per-project tmp directory listing.
     * <p>
     * Package-private so internal-cluster tests can identify per-loader files by checking whether
     * {@code stripInstallTokenInfix(name).equals(name)} is false.
     */
    static String stripInstallTokenInfix(String name) {
        return INSTALL_TOKEN_INFIX.matcher(name).replaceFirst(".mmdb");
    }

    private Path getDatabaseTmpDirectory(ProjectId projectId) {
        Path path = projectResolver.supportsMultipleProjects() ? geoipTmpDirectory.resolve(projectId.toString()) : geoipTmpDirectory;
        try {
            if (Files.exists(path) == false) {
                Files.createDirectories(path);
            }
        } catch (IOException e) {
            throw new UncheckedIOException("Failed to create geoip tmp directory for project [" + projectId + "]", e);
        }
        return path;
    }
}

View on GitHub (pinned to db6a809a66)

Solutions

1. Check the path in the error: ensure its parent exists and is writable by the Elasticsearch user.
2. Free disk space and inodes on the volume holding the tmp dir.
3. If the path collides with a file, remove the file or reconfigure the geoip tmp directory setting to a clean location.
4. Restart the node after fixing permissions so getDatabaseTmpDirectory can recreate it.

void ensureTmpDir(Path p) throws IOException {
    Files.createDirectories(p);
    if (!Files.isWritable(p)) throw new IOException("not writable: " + p);
}

try {
    service.loadDatabase(...);
} catch (UncheckedIOException e) {
    if (e.getMessage().startsWith("Failed to create geoip tmp directory")) {
        // fix permissions/ownership of the tmp dir, free disk, then restart the node
    } else throw e;
}

When it happens

Trigger: Any code path that needs a temp dir to stage a downloaded mmdb (e.g. loading/unpacking a database for a project) calls getDatabaseTmpDirectory(projectId); if the path is not creatable, the UncheckedIOException fires.

Common situations: ES process lacks write permission on the configured geoip tmp dir; the dir was removed or its parent remounted read-only; disk full or inode exhaustion; SELinux/AppArmor denying creation; a stale file exists where a directory is expected.

Related errors

• Failed to create parent directory '%s' when creating directo
• Failed to create directory '%s'
• Failed to list existing plugins
• Failed to list entitlement jars in: ${dir}
• could not remove the following files (in the order of attemp

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