alibaba/nacos · error · IllegalStateException

failed to create cache : {}{}

Error message

failed to create cache : {}{}

What it means

Thrown by DiskCache.createFileIfAbsent when a file or directory cannot be created and does not exist after the create attempt. For directories (isDir=true), mkdirs() returned false and the dir still doesn't exist; for files, createNewFile() returned false and the file still doesn't exist. This is a filesystem-level failure writing the naming service-info disk cache.

Source

Thrown at client/src/main/java/com/alibaba/nacos/client/naming/cache/DiskCache.java:180

            }
        }
        return result;
    }
    
    /**
     * Create file if absent.
     *
     * @param file  file
     * @param isDir is dir
     * @throws IOException if any io exception during create.
     */
    public static void createFileIfAbsent(File file, boolean isDir) throws IOException {
        if (file.exists()) {
            return;
        }
        boolean createResult = isDir ? file.mkdirs() : file.createNewFile();
        if (!createResult && !file.exists()) {
            throw new IllegalStateException(
                "failed to create cache : " + (isDir ? "dir" : file) + file.getPath());
        }
    }
    
    private static File makeSureCacheDirExists(String dir) throws IOException {
        File cacheDir = new File(dir);
        createFileIfAbsent(cacheDir, true);
        return cacheDir;
    }
}

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Set a writable cache directory via the Nacos client property (e.g. -Dcom.alibaba.nacos.naming.cache.dir) to a location with correct permissions and ensure the process owns it.
2. Verify the process user has write+execute permission on the cache directory and its parents; fix with chmod/chown.
3. Free disk space if the volume is full.
4. If the path conflicts (file vs dir), remove the offending entry.

Example fix

// before — default cache dir is read-only in container
System.setProperty("nacos.cache.data.init.snapshot", "true");

// after — explicit writable cache dir
System.setProperty("com.alibaba.nacos.naming.cache.dir", "/data/nacos/cache");

File dir = new File(cacheDir);
if (!dir.exists() && !dir.mkdirs()) {
    throw new IllegalStateException("Cannot create cache dir " + dir + " — check permissions/disk");
}
if (!dir.canWrite()) {
    throw new IllegalStateException("Cache dir not writable: " + dir);
}

When it happens

Trigger: The cache directory's parent is not writable (permissions); the path points to a location with no free disk space; a file exists at the path where a directory is expected (or vice versa); the disk is read-only; the configured cache dir is invalid/relative to an inaccessible working directory.

Common situations: Containers/Pods with restrictive volume mounts or read-only filesystems where the cache path isn't mounted writable; wrong JM_SNAPSHOT_DIR / user.home causing the cache to land on an unwritable path; disk-full conditions; security policies denying mkdir.

Related errors

• delete fail
• Failed to delete: {path}
• -401
• {} does not exist
• {} is not a directory

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/621bc11db7c23b36. Report an issue: GitHub.