apache/dubbo · error · PathNotExclusiveException

{} is not exclusive. Maybe multiple Dubbo instances are usin

Error message

{} is not exclusive. Maybe multiple Dubbo instances are using the same folder.

What it means

Thrown as PathNotExclusiveException by tryFileLock when dirLock is null, meaning the FileChannel.tryLock() call did not grant an exclusive lock. This happens when another JVM/Dubbo instance already holds the OS-level lock on the same cache file, or an OverlappingFileLockException was caught within the same JVM.

Source

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

    private static void tryFileLock(FileCacheStore.Builder builder, String fileName) throws PathNotExclusiveException {
        File lockFile = new File(fileName + ".lock");

        FileLock dirLock;
        try {
            lockFile.createNewFile();
            if (!lockFile.exists()) {
                throw new AssertionError("Failed to create lock file " + lockFile);
            }
            FileChannel lockFileChannel = new RandomAccessFile(lockFile, "rw").getChannel();
            dirLock = lockFileChannel.tryLock();
        } catch (OverlappingFileLockException ofle) {
            dirLock = null;
        } catch (IOException ioe) {
            throw new RuntimeException(ioe);
        }

        if (dirLock == null) {
            throw new PathNotExclusiveException(
                    fileName + " is not exclusive. Maybe multiple Dubbo instances are using the same folder.");
        }

        lockFile.deleteOnExit();
        builder.directoryLock(dirLock).lockFile(lockFile);
    }

    static void removeCache(String cacheFileName) {
        cacheMap.remove(cacheFileName);
    }

    private static class PathNotExclusiveException extends Exception {
        public PathNotExclusiveException(String msg) {
            super(msg);
        }
    }
}

View on GitHub (pinned to 3a3043227f)

Solutions

1. Give each Dubbo instance its own cache base path (distinct HOME or explicit basePath) so lock files do not collide.
2. If sharing a filesystem is intentional, ensure only one Dubbo instance uses a given cache file at a time.
3. In multi-webapp containers, isolate ClassLoaders/cache paths per application.
4. Disable file caching (enableFileCache=false) for instances that do not need persistent cache.

Example fix

// before: two instances share default ~/.dubbo
FileCacheStoreFactory.getInstance(null, "meta");
// after: per-instance path
FileCacheStoreFactory.getInstance("/data/dubbo/instance-1/.dubbo", "meta");

// Give each instance a distinct cache base path
String basePath = "/data/dubbo/" + System.getProperty("app.id", "default") + "/.dubbo";
FileCacheStoreFactory.getInstance(basePath, cacheName);

try {
    FileCacheStoreFactory.getInstance(basePath, cacheName);
} catch (Exception e) {
    // path not exclusive; another instance owns it — use a unique path or disable cache
    FileCacheStoreFactory.getInstance(uniqueBasePath, cacheName, false);
}

When it happens

Trigger: Two or more Dubbo instances (or two ClassLoaders in one JVM) point at the same cache file path and both call getInstance; the second one's tryLock returns null or throws OverlappingFileLockException, so dirLock is null.

Common situations: Multiple application instances share a home directory or a common cache base path on a shared filesystem. Running several Dubbo processes in the same container with HOME pointing to one volume. Two webapps in one Tomcat both loading Dubbo against the same cache.

Related errors

• Failed to release cache path's lock file:{}
• Failed to create lock file {}
• Cache store path can't be created: {}
• INTERNAL_ERROR
• Failed to acquire read lock on invokerRefreshLock within tim

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