What causes "Failed to create lock file {}" in apache/dubbo?

Check the cache directory for conflicting entries (a directory named .dubbo.cache.lock) and remove them.

apache/dubbo · error · AssertionError

Failed to create lock file {}

Error message

Failed to create lock file {}

What it means

Thrown as an AssertionError by tryFileLock when lockFile.createNewFile() either returns false or the file still does not exist afterward. The lock file is required to acquire an exclusive FileLock; if it cannot be created, the locking precondition has failed.

Source

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

            logger.warn(
                    COMMON_CACHE_PATH_INACCESSIBLE,
                    "inaccessible of cache path",
                    "",
                    "Failed to create file store cache. Local file cache will be disabled. Cache file name: " + name,
                    t);

            return FileCacheStore.Empty.getInstance(name);
        }
    }

    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);
    }

View on GitHub (pinned to 3a3043227f)

Solutions

Check the cache directory for conflicting entries (a directory named <cacheName>.dubbo.cache.lock) and remove them.
Confirm the running user has write permission on the cache directory.
Retry after clearing stale .lock files when no Dubbo instance is running.
Disable file caching (enableFileCache=false) if the environment cannot support lock files.

Defensive patterns

Strategy: try-catch

Validate before calling

File lockFile = new File(cacheDir, cacheName + ".lock");
if (lockFile.exists() && !lockFile.isFile()) {
    // a directory occupies the lock name; remove or rename before creating FileCacheStore
}

Try / catch

try {
    FileCacheStoreFactory.getInstance(basePath, cacheName);
} catch (AssertionError | RuntimeException e) {
    // lock file creation failed; clear conflicting entries or disable cache
    FileCacheStoreFactory.getInstance(basePath, cacheName, false);
}

Prevention

Keep the cache directory free of conflicting entries named like the lock file.
Confirm write permission on the cache directory.
Clear stale .lock files when no Dubbo instance is running.
Use enableFileCache=false if the environment cannot create lock files.

When it happens

Trigger: FileCacheStoreFactory.tryFileLock calls lockFile.createNewFile() but the file is not creatable (e.g. a directory of the same name exists, or the parent is read-only) and the subsequent exists() check fails, triggering the assertion.

Common situations: Another process holds the path, the cache directory permissions changed, or a stale directory entry blocks file creation. Rare in practice because the preceding createDirectories usually catches permission issues; an AssertionError indicates an unexpected filesystem state.

Related errors

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