{"record":{"id":"787ef60f97a2f6fd","repo":"aeron-io/aeron","slug":"driverversion-driverversion-insufficient-for-clientversion","errorCode":null,"errorMessage":"driverVersion=<driverVersion> insufficient for clientVersion=<clientVersion>","messagePattern":"driverVersion=<driverVersion> insufficient for clientVersion=<clientVersion>","errorType":"exception","errorClass":"AeronException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/CommonContext.java","lineNumber":1434,"sourceCode":"                final UnsafeBuffer metaDataBuffer =\n                    CncFileDescriptor.createMetaDataBuffer(fileChannel.map(READ_WRITE, 0, fileSize));\n\n                int cncVersion;\n                while (0 == (cncVersion = metaDataBuffer.getIntVolatile(CncFileDescriptor.cncVersionOffset(0))))\n                {\n                    if (clock.time() > deadlineMs)\n                    {\n                        throw new DriverTimeoutException(\"CnC file is created but not initialised: \" +\n                            cncFile.getAbsolutePath());\n                    }\n\n                    sleep(Aeron.Configuration.AWAITING_IDLE_SLEEP_MS);\n                }\n\n                CncFileDescriptor.checkVersion(cncVersion);\n                if (SemanticVersion.minor(cncVersion) < SemanticVersion.minor(CncFileDescriptor.CNC_VERSION))\n                {\n                    throw new AeronException(\"driverVersion=\" + SemanticVersion.toString(cncVersion) +\n                        \" insufficient for clientVersion=\" +\n                        SemanticVersion.toString(CncFileDescriptor.CNC_VERSION));\n                }\n\n                return metaDataBuffer;\n            }\n            catch (final NoSuchFileException | AccessDeniedException ignore)\n            {\n            }\n            catch (final FileSystemException ex)\n            {\n                // JDK exception translation does not handle `ERROR_SHARING_VIOLATION (32)` and returns\n                // FileSystemException with the error \"The process cannot access the file because it is being\n                // used by another process.\". Our current thinking is that matching by text is too brittle due\n                // to error message being locale-sensitive on Windows. Therefore, we are going to retry on any\n                // FileSystemException when running on Windows.\n                if (SystemUtil.isWindows())\n                {","sourceCodeStart":1416,"sourceCodeEnd":1452,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/CommonContext.java#L1416-L1452","documentation":"Beyond major-version compatibility, the client requires the driver's CnC version to be at least the client's minor version, because an older driver lacks features/semantics the newer client depends on. If the driver's minor version is lower, this AeronException is thrown naming both versions.","triggerScenarios":"Connecting a newer Aeron client (e.g. 1.46.x) to a driver running an older minor version (e.g. 1.44.x): SemanticVersion.minor(cncVersion) < minor of the client's CNC_VERSION.","commonSituations":"Rolling upgrades where the client jar was updated but the driver process was not restarted; driver container pinned to an old image; dependency management pulling a newer aeron-client than the bundled driver.","solutions":["Upgrade the media driver to at least the client's Aeron version and restart it","Downgrade the client library to match the driver version","In rolling deployments, upgrade drivers before clients","Pin aeron-client and aeron-driver (or aeron-all) to the same version in your build"],"exampleFix":"// before (mismatched deps)\nimplementation 'io.aeron:aeron-client:1.46.0'\n// driver running 1.44.1\n\n// after\nimplementation 'io.aeron:aeron-all:1.46.0'\n// restart driver on 1.46.0","handlingStrategy":"validation","validationCode":"// after mapping CnC, before relying on driver features\nint cncVersion = CncFileDescriptor.cncVersion(metaDataBuffer);\nif (SemanticVersion.minor(cncVersion) < SemanticVersion.minor(CncFileDescriptor.CNC_VERSION)) {\n    throw new IllegalStateException(\"Driver \" + SemanticVersion.toString(cncVersion) + \" older than client - upgrade driver\");\n}","typeGuard":null,"tryCatchPattern":"try { Aeron aeron = Aeron.connect(ctx); } catch (AeronException e) { if (e.getMessage().contains(\"insufficient for clientVersion\")) { upgradeDriverToClientVersion(); } else { throw e; } }","preventionTips":["Pin aeron-client/aeron-driver/aeron-all to identical versions in builds","In rolling upgrades, update drivers before clients","Assert driver version at startup in integration tests"],"tags":["aeron","version-compatibility","driver","upgrade"],"backgroundTag":"schema-validation-failed","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}