aeron-io/aeron · error · AeronException

driverVersion= insufficient for clientVersion=

Error message

driverVersion=<driverVersion> insufficient for clientVersion=<clientVersion>

What it means

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.

Solutions

1. Upgrade the media driver to at least the client's Aeron version and restart it
2. Downgrade the client library to match the driver version
3. In rolling deployments, upgrade drivers before clients
4. Pin aeron-client and aeron-driver (or aeron-all) to the same version in your build

Example fix

// before (mismatched deps)
implementation 'io.aeron:aeron-client:1.46.0'
// driver running 1.44.1

// after
implementation 'io.aeron:aeron-all:1.46.0'
// restart driver on 1.46.0

// after mapping CnC, before relying on driver features
int cncVersion = CncFileDescriptor.cncVersion(metaDataBuffer);
if (SemanticVersion.minor(cncVersion) < SemanticVersion.minor(CncFileDescriptor.CNC_VERSION)) {
    throw new IllegalStateException("Driver " + SemanticVersion.toString(cncVersion) + " older than client - upgrade driver");
}

try { Aeron aeron = Aeron.connect(ctx); } catch (AeronException e) { if (e.getMessage().contains("insufficient for clientVersion")) { upgradeDriverToClientVersion(); } else { throw e; } }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Driver events adapter is invalid
• no response from MediaDriver within
• MediaDriver ( ) keepalive: age= ms > timeout= ms
• unexpected close of heartbeat timestamp counter
• CnC version not compatible: app=

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/787ef60f97a2f6fd. Report an issue: GitHub.

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/CommonContext.java:1434

                final UnsafeBuffer metaDataBuffer =
                    CncFileDescriptor.createMetaDataBuffer(fileChannel.map(READ_WRITE, 0, fileSize));

                int cncVersion;
                while (0 == (cncVersion = metaDataBuffer.getIntVolatile(CncFileDescriptor.cncVersionOffset(0))))
                {
                    if (clock.time() > deadlineMs)
                    {
                        throw new DriverTimeoutException("CnC file is created but not initialised: " +
                            cncFile.getAbsolutePath());
                    }

                    sleep(Aeron.Configuration.AWAITING_IDLE_SLEEP_MS);
                }

                CncFileDescriptor.checkVersion(cncVersion);
                if (SemanticVersion.minor(cncVersion) < SemanticVersion.minor(CncFileDescriptor.CNC_VERSION))
                {
                    throw new AeronException("driverVersion=" + SemanticVersion.toString(cncVersion) +
                        " insufficient for clientVersion=" +
                        SemanticVersion.toString(CncFileDescriptor.CNC_VERSION));
                }

                return metaDataBuffer;
            }
            catch (final NoSuchFileException | AccessDeniedException ignore)
            {
            }
            catch (final FileSystemException ex)
            {
                // JDK exception translation does not handle `ERROR_SHARING_VIOLATION (32)` and returns
                // FileSystemException with the error "The process cannot access the file because it is being
                // used by another process.". Our current thinking is that matching by text is too brittle due
                // to error message being locale-sensitive on Windows. Therefore, we are going to retry on any
                // FileSystemException when running on Windows.
                if (SystemUtil.isWindows())
                {

View on GitHub (pinned to 6d60124e15)