{"record":{"id":"62994f61e1433639","repo":"aeron-io/aeron","slug":"cnc-version-not-compatible-app-appversion-file-fileversion","errorCode":null,"errorMessage":"CnC version not compatible: app=<appVersion> file=<fileVersion>","messagePattern":"CnC version not compatible: app=<appVersion> file=<fileVersion>","errorType":"exception","errorClass":"AeronException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/CncFileDescriptor.java","lineNumber":470,"sourceCode":"     * @param metaDataBuffer for the CnC file.\n     * @return the file page size.\n     */\n    public static int filePageSize(final DirectBuffer metaDataBuffer)\n    {\n        return metaDataBuffer.getInt(FILE_PAGE_SIZE_FIELD_OFFSET);\n    }\n\n    /**\n     * Check the version of the CnC file is compatible with application.\n     *\n     * @param cncVersion of the CnC file.\n     * @throws AeronException if the major versions are not compatible.\n     */\n    public static void checkVersion(final int cncVersion)\n    {\n        if (SemanticVersion.major(CNC_VERSION) != SemanticVersion.major(cncVersion))\n        {\n            throw new AeronException(\"CnC version not compatible:\" +\n                \" app=\" + SemanticVersion.toString(CNC_VERSION) +\n                \" file=\" + SemanticVersion.toString(cncVersion));\n        }\n    }\n\n    /**\n     * Is the provided length for the CnC file sufficient given what is stored in the metadata.\n     *\n     * @param metaDataBuffer for the CnC file.\n     * @param cncFileLength  to check if it is sufficient based on what is stored in the metadata.\n     * @return true is the length is correct otherwise false.\n     */\n    public static boolean isCncFileLengthSufficient(final DirectBuffer metaDataBuffer, final int cncFileLength)\n    {\n        final int metadataRequiredLength =\n            META_DATA_LENGTH +\n            metaDataBuffer.getInt(TO_DRIVER_BUFFER_LENGTH_FIELD_OFFSET) +\n            metaDataBuffer.getInt(TO_CLIENTS_BUFFER_LENGTH_FIELD_OFFSET) +","sourceCodeStart":452,"sourceCodeEnd":488,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/CncFileDescriptor.java#L452-L488","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Align client and driver to the same Aeron major version","Delete the stale CnC file (cnc.dat) in the aeron.dir and restart the media driver","Restart the media driver so it recreates the CnC file with its own version"],"exampleFix":"// before\nAeron aeron = Aeron.connect(); // client 1.44 against old driver's CnC\n\n// after\n// upgrade driver to match client major version, then:\nAeron aeron = Aeron.connect(new Aeron.Context().aeronDirectoryName(\"/dev/shm/aeron\"));","handlingStrategy":"validation","validationCode":"// before connecting\ntry (MappedByteBuffer cnc = mapCnc()) {\n    int v = CncFileDescriptor.cncVersion(cnc);\n    if (SemanticVersion.major(v) != SemanticVersion.major(CncFileDescriptor.CNC_VERSION)) {\n        throw new IllegalStateException(\"Aeron client/driver major version mismatch: \" + SemanticVersion.toString(v));\n    }\n}","typeGuard":null,"tryCatchPattern":"try { Aeron aeron = Aeron.connect(ctx); } catch (AeronException e) { if (e.getMessage().startsWith(\"CnC version not compatible\")) { upgradeDriverOrDowngradeClient(); } else { throw e; } }","preventionTips":["Keep client and driver on the same Aeron release","Restart the driver whenever you upgrade the client across versions","Clear stale cnc.dat files from aeron.dir after upgrades"],"tags":["aeron","version-compatibility","cnc-file"],"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"}