aeron-io/aeron · error · AeronException

CnC version not compatible: app=

Error message

CnC version not compatible: app=<appVersion> file=<fileVersion>

What it means

Aeron's CnC (command-and-control) file carries a version field that must have the same major version as the client library. checkVersion throws when the major version in the file differs from the client's CNC_VERSION, meaning the file layout is incompatible.

Solutions

  1. Align client and driver to the same Aeron major version
  2. Delete the stale CnC file (cnc.dat) in the aeron.dir and restart the media driver
  3. Restart the media driver so it recreates the CnC file with its own version

Example fix

// before
Aeron aeron = Aeron.connect(); // client 1.44 against old driver's CnC

// after
// upgrade driver to match client major version, then:
Aeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName("/dev/shm/aeron"));
Defensive patterns

Strategy: validation

Validate before calling

// before connecting
try (MappedByteBuffer cnc = mapCnc()) {
    int v = CncFileDescriptor.cncVersion(cnc);
    if (SemanticVersion.major(v) != SemanticVersion.major(CncFileDescriptor.CNC_VERSION)) {
        throw new IllegalStateException("Aeron client/driver major version mismatch: " + SemanticVersion.toString(v));
    }
}

Try / catch

try { Aeron aeron = Aeron.connect(ctx); } catch (AeronException e) { if (e.getMessage().startsWith("CnC version not compatible")) { upgradeDriverOrDowngradeClient(); } else { throw e; } }

Prevention

When it happens

Trigger: Connecting an Aeron client to a CnC file written by a driver of a different major version, e.g. Aeron.connect() or CommonContext driver awaiting against a stale cnc.dat from another Aeron major release.

Common situations: Upgrading the client jar without restarting/rebuilding the driver (or vice versa); leftover CnC file in aeron.dir from an old installation; mixing client and driver versions from different releases in the same application.

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

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/CncFileDescriptor.java:470

     * @param metaDataBuffer for the CnC file.
     * @return the file page size.
     */
    public static int filePageSize(final DirectBuffer metaDataBuffer)
    {
        return metaDataBuffer.getInt(FILE_PAGE_SIZE_FIELD_OFFSET);
    }

    /**
     * Check the version of the CnC file is compatible with application.
     *
     * @param cncVersion of the CnC file.
     * @throws AeronException if the major versions are not compatible.
     */
    public static void checkVersion(final int cncVersion)
    {
        if (SemanticVersion.major(CNC_VERSION) != SemanticVersion.major(cncVersion))
        {
            throw new AeronException("CnC version not compatible:" +
                " app=" + SemanticVersion.toString(CNC_VERSION) +
                " file=" + SemanticVersion.toString(cncVersion));
        }
    }

    /**
     * Is the provided length for the CnC file sufficient given what is stored in the metadata.
     *
     * @param metaDataBuffer for the CnC file.
     * @param cncFileLength  to check if it is sufficient based on what is stored in the metadata.
     * @return true is the length is correct otherwise false.
     */
    public static boolean isCncFileLengthSufficient(final DirectBuffer metaDataBuffer, final int cncFileLength)
    {
        final int metadataRequiredLength =
            META_DATA_LENGTH +
            metaDataBuffer.getInt(TO_DRIVER_BUFFER_LENGTH_FIELD_OFFSET) +
            metaDataBuffer.getInt(TO_CLIENTS_BUFFER_LENGTH_FIELD_OFFSET) +

View on GitHub (pinned to 6d60124e15)