apache/dubbo · error · RuntimeException

Failed to release cache path's lock file:{}

Error message

Failed to release cache path's lock file:{}

What it means

Thrown by FileCacheStore.unlock() when releasing the FileLock, closing the channel, or deleting the lock file raises an IOException. The cache (e.g. service-name mapping or metadata cache) could not cleanly release its directory lock during shutdown/refresh, so the error is wrapped in a RuntimeException and propagated.

Source

Thrown at dubbo-common/src/main/java/org/apache/dubbo/common/cache/FileCacheStore.java:108

        }
        return properties;
    }

    private void unlock() {
        if (directoryLock != null && directoryLock.isValid()) {
            try {
                directoryLock.release();
                directoryLock.channel().close();
                deleteFile(lockFile);
            } catch (IOException e) {
                logger.error(
                        COMMON_CACHE_PATH_INACCESSIBLE,
                        "inaccessible of cache path",
                        "",
                        "Failed to release cache path's lock file:" + lockFile,
                        e);

                throw new RuntimeException("Failed to release cache path's lock file:" + lockFile, e);
            }
        }
    }

    public synchronized void refreshCache(Map<String, String> properties, String comment, long maxFileSize) {
        if (CollectionUtils.isEmptyMap(properties)) {
            return;
        }

        try (LimitedLengthBufferedWriter bw = new LimitedLengthBufferedWriter(
                new OutputStreamWriter(new FileOutputStream(cacheFile, false), StandardCharsets.UTF_8), maxFileSize)) {

            bw.write("#" + comment);
            bw.newLine();
            bw.write("#" + new Date());
            bw.newLine();

            for (Map.Entry<String, String> e : properties.entrySet()) {

View on GitHub (pinned to 3a3043227f)

Solutions

  1. Ensure the cache directory (default ~/.dubbo) is writable and on a local, non-read-only filesystem.
  2. Remove stale .lock files from the cache directory if no Dubbo instance is running.
  3. If running in a container, mount a writable tmpfs or emptyDir for the cache path instead of a read-only volume.
  4. Disable file cache (pass enableFileCache=false to FileCacheStoreFactory.getInstance) if the environment cannot guarantee lock semantics.

Example fix

// before: cache on read-only mount
FileCacheStoreFactory.getInstance("/readOnly/.dubbo", "meta");
// after: writable local path or disabled
FileCacheStoreFactory.getInstance(null, "meta", false);
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check the cache directory is writable and lock is valid
File dir = new File(System.getProperty("user.home"), ".dubbo");
if (!dir.canWrite()) {
    // disable file cache or fix permissions before creating FileCacheStore
}

Try / catch

try {
    cacheStore.close(); // or refreshCache
} catch (RuntimeException e) {
    if (e.getCause() instanceof IOException) {
        // lock release failed; clear stale lock file and continue
    }
}

Prevention

When it happens

Trigger: FileCacheStore is being closed/refreshed and directoryLock.release(), channel().close(), or deleteFile(lockFile) throws IOException. Happens when the lock file was already deleted, the channel is already closed, or the filesystem rejects the operation.

Common situations: Running in a container (Docker/Kubernetes) with an ephemeral or read-only mounted volume where the cache directory lives. Multiple JVMs or a previous crashed Dubbo instance left the lock in an odd state. NFS or network filesystems that delay lock release.

Related errors

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