{"record":{"id":"621bc11db7c23b36","repo":"alibaba/nacos","slug":"failed-to-create-cache","errorCode":null,"errorMessage":"failed to create cache : {}{}","messagePattern":"failed to create cache : (.+?)(.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/com/alibaba/nacos/client/naming/cache/DiskCache.java","lineNumber":180,"sourceCode":"            }\n        }\n        return result;\n    }\n    \n    /**\n     * Create file if absent.\n     *\n     * @param file  file\n     * @param isDir is dir\n     * @throws IOException if any io exception during create.\n     */\n    public static void createFileIfAbsent(File file, boolean isDir) throws IOException {\n        if (file.exists()) {\n            return;\n        }\n        boolean createResult = isDir ? file.mkdirs() : file.createNewFile();\n        if (!createResult && !file.exists()) {\n            throw new IllegalStateException(\n                \"failed to create cache : \" + (isDir ? \"dir\" : file) + file.getPath());\n        }\n    }\n    \n    private static File makeSureCacheDirExists(String dir) throws IOException {\n        File cacheDir = new File(dir);\n        createFileIfAbsent(cacheDir, true);\n        return cacheDir;\n    }\n}\n","sourceCodeStart":162,"sourceCodeEnd":191,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/client/src/main/java/com/alibaba/nacos/client/naming/cache/DiskCache.java#L162-L191","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Verify the process user has write+execute permission on the cache directory and its parents; fix with chmod/chown.","Free disk space if the volume is full.","If the path conflicts (file vs dir), remove the offending entry."],"exampleFix":"// before — default cache dir is read-only in container\nSystem.setProperty(\"nacos.cache.data.init.snapshot\", \"true\");\n\n// after — explicit writable cache dir\nSystem.setProperty(\"com.alibaba.nacos.naming.cache.dir\", \"/data/nacos/cache\");","handlingStrategy":"validation","validationCode":"File dir = new File(cacheDir);\nif (!dir.exists() && !dir.mkdirs()) {\n    throw new IllegalStateException(\"Cannot create cache dir \" + dir + \" — check permissions/disk\");\n}\nif (!dir.canWrite()) {\n    throw new IllegalStateException(\"Cache dir not writable: \" + dir);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Point the cache dir to a writable volume in containers.","Set the naming cache dir to a writable path via client properties and verify permissions at startup.","Ensure the process user owns/has write permission on the cache dir and parents.","Keep disk space available on the cache volume."],"tags":["naming","disk-cache","filesystem","io","permissions"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}