{"record":{"id":"bc15e911f402656d","repo":"gradle/gradle","slug":"unexpected-lock-protocol-found-in-lock-file-expec-bc15e9","errorCode":null,"errorMessage":"Unexpected lock protocol found in lock file. Expected %s, found %s.","messagePattern":"Unexpected lock protocol found in lock file\\. Expected (.+?), found (.+?)\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"platforms/core-execution/persistent-cache/src/main/java/org/gradle/cache/internal/filelock/LockStateAccess.java","lineNumber":84,"sourceCode":"        try {\n            byte[] buffer = new byte[stateRegionSize];\n            lockFileAccess.seek(REGION_START);\n\n            int readPos = 0;\n            while (readPos < buffer.length) {\n                int nread = lockFileAccess.read(buffer, readPos, buffer.length - readPos);\n                if (nread < 0) {\n                    break;\n                }\n                readPos += nread;\n            }\n\n            ByteArrayInputStream inputStream = new ByteArrayInputStream(buffer, 0, readPos);\n            DataInputStream dataInput = new DataInputStream(inputStream);\n\n            byte protocolVersion = dataInput.readByte();\n            if (protocolVersion != protocol.getVersion()) {\n                throw new IllegalStateException(String.format(\"Unexpected lock protocol found in lock file. Expected %s, found %s.\", protocol.getVersion(), protocolVersion));\n            }\n            return protocol.read(dataInput);\n        } catch (EOFException e) {\n            return protocol.createInitialState();\n        }\n    }\n\n    public FileLockOutcome tryLock(RandomAccessFile lockFileAccess, boolean shared) throws IOException {\n        try {\n            FileLock fileLock = lockFileAccess.getChannel().tryLock(REGION_START, stateRegionSize, shared);\n            if (fileLock == null) {\n                return FileLockOutcome.LOCKED_BY_ANOTHER_PROCESS;\n            } else {\n                return FileLockOutcome.acquired(fileLock);\n            }\n        } catch (OverlappingFileLockException e) {\n            return FileLockOutcome.LOCKED_BY_THIS_PROCESS;\n        }","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/gradle/gradle/blob/534f27719b66953f95cc907aae7f2c1b12f5482d/platforms/core-execution/persistent-cache/src/main/java/org/gradle/cache/internal/filelock/LockStateAccess.java#L66-L102","documentation":"LockStateAccess parses the state region of a cache lock file, which is also version-prefixed; a mismatch between the on-disk protocol byte and the running Gradle's protocol raises this IllegalStateException. An empty or short region is not an error (EOFException yields the initial state), so it only fires when a complete record written by a different protocol version exists. Practically, another Gradle generation wrote this lock state.","triggerScenarios":"Acquiring a cache lock whose state region was persisted by a Gradle build with a different lock state protocol, e.g. after a version switch with surviving daemons or shared caches.","commonSituations":"Switching Gradle versions while old daemons hold locks, mixed IDE/CLI versions on one machine, CI sharing a cache volume with developer workstations.","solutions":["Stop every running Gradle daemon across all installed versions, then retry","Delete the lock files for the affected cache so fresh state is written","Keep a single Gradle version per GRADLE_USER_HOME","Standardize the Gradle wrapper version across teams and CI"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    lockStateAccess.readState(lockFileAccess);\n} catch (IllegalStateException e) {\n    if (String.valueOf(e.getMessage()).startsWith(\"Unexpected lock protocol\")) {\n        // stale lock state from another Gradle version: delete the lock file\n    }\n}","preventionTips":["Stop all daemons after a Gradle upgrade or downgrade","Do not share GRADLE_USER_HOME between different Gradle versions","Automate wrapper-version pinning in CI"],"tags":["gradle","file-lock","version-mismatch","persistent-cache"],"backgroundTag":"lock-protocol-version-mismatch","analyzedSha":"534f27719b66953f95cc907aae7f2c1b12f5482d","analyzedAt":"2026-08-22T08:09:12.375Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}