{"record":{"id":"2fa961efab524485","repo":"apache/dubbo","slug":"cache-store-path-can-t-be-created","errorCode":null,"errorMessage":"Cache store path can't be created: {}","messagePattern":"Cache store path can't be created: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"dubbo-common/src/main/java/org/apache/dubbo/common/cache/FileCacheStoreFactory.java","lineNumber":109,"sourceCode":"\n        File candidate = new File(basePath);\n        Path path = candidate.toPath();\n\n        // ensure cache store path exists\n        if (!candidate.isDirectory()) {\n            try {\n                Files.createDirectories(path);\n            } catch (IOException e) {\n                // 0-3 - cache path inaccessible\n\n                logger.error(\n                        COMMON_CACHE_PATH_INACCESSIBLE,\n                        \"inaccessible of cache path\",\n                        \"\",\n                        \"Cache store path can't be created: \",\n                        e);\n\n                throw new RuntimeException(\"Cache store path can't be created: \" + candidate, e);\n            }\n        }\n\n        cacheName = safeName(cacheName);\n        if (!cacheName.endsWith(SUFFIX)) {\n            cacheName = cacheName + SUFFIX;\n        }\n\n        String cacheFilePath = basePath + File.separator + cacheName;\n\n        return ConcurrentHashMapUtils.computeIfAbsent(cacheMap, cacheFilePath, k -> getFile(k, enableFileCache));\n    }\n\n    /**\n     * sanitize a name for valid file or directory name\n     *\n     * @param name origin file name\n     * @return sanitized version of name","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/apache/dubbo/blob/3a3043227f5571d25eb2889de5bca22f2914843b/dubbo-common/src/main/java/org/apache/dubbo/common/cache/FileCacheStoreFactory.java#L91-L127","documentation":"Thrown by FileCacheStoreFactory.getInstance when Files.createDirectories(path) fails with an IOException while trying to create the cache base directory. The cache (mapping/meta) cannot operate without its directory, so the error is wrapped and rethrown as a RuntimeException.","triggerScenarios":"The basePath (default $HOME/.dubbo, or a custom path) does not exist and cannot be created because of insufficient permissions, a read-only filesystem, or a path conflict (e.g. a file exists where a directory is expected).","commonSituations":"Running Dubbo under a user without write permission to the home directory or the configured cache path. Container deployments with a read-only root filesystem. A misconfigured cache base path pointing to a protected system directory.","solutions":["Verify the user running Dubbo has write permission on the cache base path (default $HOME/.dubbo).","Set a writable explicit path, e.g. pass basePath to getInstance pointing to a writable directory.","In containers, mount a writable volume at the cache path or set HOME to a writable location.","If filesystem caching is not needed, call getInstance with enableFileCache=false to skip directory creation."],"exampleFix":"// before\nFileCacheStoreFactory.getInstance(\"/var/lock/.dubbo\", \"meta\");\n// after\nFileCacheStoreFactory.getInstance(\"/opt/app/data/.dubbo\", \"meta\");\n// or disable file cache\nFileCacheStoreFactory.getInstance(null, \"meta\", false);","handlingStrategy":"validation","validationCode":"String basePath = customPath != null ? customPath\n    : System.getProperty(\"user.home\") + File.separator + \".dubbo\";\nFile dir = new File(basePath);\nif (!dir.exists() && !dir.mkdirs()) {\n    // cannot create; pass enableFileCache=false or fix permissions\n}\nFileCacheStoreFactory.getInstance(basePath, cacheName);","typeGuard":"static boolean cachePathWritable(String path) {\n    File f = new File(path);\n    return f.isDirectory() && f.canWrite() || f.mkdirs();\n}","tryCatchPattern":"try {\n    FileCacheStoreFactory.getInstance(basePath, cacheName);\n} catch (RuntimeException e) {\n    if (e.getCause() instanceof java.io.IOException) {\n        // path creation failed; disable file cache\n        FileCacheStoreFactory.getInstance(basePath, cacheName, false);\n    }\n}","preventionTips":["Ensure the Dubbo process user has write permission on the cache directory.","Set an explicit writable basePath instead of relying on a protected default.","In containers, mount a writable volume at the cache path or set HOME appropriately.","Fall back to enableFileCache=false when the filesystem is read-only."],"tags":["cache","file-io","filesystem","permissions","configuration"],"backgroundTag":null,"analyzedSha":"3a3043227f5571d25eb2889de5bca22f2914843b","analyzedAt":"2026-08-14T00:43:19.853Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}