apache/dubbo · error · RuntimeException

Cache store path can't be created: {}

Error message

Cache store path can't be created: {}

What it means

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.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/cache/FileCacheStoreFactory.java:109

        File candidate = new File(basePath);
        Path path = candidate.toPath();

        // ensure cache store path exists
        if (!candidate.isDirectory()) {
            try {
                Files.createDirectories(path);
            } catch (IOException e) {
                // 0-3 - cache path inaccessible

                logger.error(
                        COMMON_CACHE_PATH_INACCESSIBLE,
                        "inaccessible of cache path",
                        "",
                        "Cache store path can't be created: ",
                        e);

                throw new RuntimeException("Cache store path can't be created: " + candidate, e);
            }
        }

        cacheName = safeName(cacheName);
        if (!cacheName.endsWith(SUFFIX)) {
            cacheName = cacheName + SUFFIX;
        }

        String cacheFilePath = basePath + File.separator + cacheName;

        return ConcurrentHashMapUtils.computeIfAbsent(cacheMap, cacheFilePath, k -> getFile(k, enableFileCache));
    }

    /**
     * sanitize a name for valid file or directory name
     *
     * @param name origin file name
     * @return sanitized version of name

View on GitHub (pinned to 3a3043227f)

Solutions

1. Verify the user running Dubbo has write permission on the cache base path (default $HOME/.dubbo).
2. Set a writable explicit path, e.g. pass basePath to getInstance pointing to a writable directory.
3. In containers, mount a writable volume at the cache path or set HOME to a writable location.
4. If filesystem caching is not needed, call getInstance with enableFileCache=false to skip directory creation.

Example fix

// before
FileCacheStoreFactory.getInstance("/var/lock/.dubbo", "meta");
// after
FileCacheStoreFactory.getInstance("/opt/app/data/.dubbo", "meta");
// or disable file cache
FileCacheStoreFactory.getInstance(null, "meta", false);

String basePath = customPath != null ? customPath
    : System.getProperty("user.home") + File.separator + ".dubbo";
File dir = new File(basePath);
if (!dir.exists() && !dir.mkdirs()) {
    // cannot create; pass enableFileCache=false or fix permissions
}
FileCacheStoreFactory.getInstance(basePath, cacheName);

static boolean cachePathWritable(String path) {
    File f = new File(path);
    return f.isDirectory() && f.canWrite() || f.mkdirs();
}

try {
    FileCacheStoreFactory.getInstance(basePath, cacheName);
} catch (RuntimeException e) {
    if (e.getCause() instanceof java.io.IOException) {
        // path creation failed; disable file cache
        FileCacheStoreFactory.getInstance(basePath, cacheName, false);
    }
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Failed to release cache path's lock file:{}
• Failed to create lock file {}
• {} is not exclusive. Maybe multiple Dubbo instances are usin
• already exists bean with same name and type, name=${name}, t
• expected single matching bean but found ${size} candidates f

AI-assisted analysis of apache/dubbo@3a3043227f (2026-08-14). Data as JSON: /api/errors/2fa961efab524485. Report an issue: GitHub.