{"record":{"id":"cb8fa8c1d2868c12","repo":"aeron-io/aeron","slug":"incompatible-catalog-file-version-semanticversion-tostring","errorCode":null,"errorMessage":"incompatible catalog file version \" + SemanticVersion.toString(version) + \", archive software is \" + SemanticVersion.toString(ArchiveMarkFile.SEMANTIC_VERSION)","messagePattern":"incompatible catalog file version \" \\+ SemanticVersion\\.toString\\(version\\) \\+ \", archive software is \" \\+ SemanticVersion\\.toString\\(ArchiveMarkFile\\.SEMANTIC_VERSION\\)","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"critical","filePath":"aeron-archive/src/main/java/io/aeron/archive/Catalog.java","lineNumber":208,"sourceCode":"            {\n                CloseHelper.close(catalogFileChannel);\n                LangUtil.rethrowUnchecked(ex);\n            }\n\n            catalogChannel = catalogFileChannel;\n            initBuffers(catalogMappedByteBuffer);\n\n            final UnsafeBuffer catalogHeaderBuffer = new UnsafeBuffer(catalogByteBuffer);\n            catalogHeaderDecoder.wrap(\n                catalogHeaderBuffer, 0, CatalogHeaderDecoder.BLOCK_LENGTH, CatalogHeaderDecoder.SCHEMA_VERSION);\n            catalogHeaderEncoder.wrap(catalogHeaderBuffer, 0);\n\n            if (catalogExists)\n            {\n                final int version = catalogHeaderDecoder.version();\n                if (SemanticVersion.major(version) != ArchiveMarkFile.MAJOR_VERSION)\n                {\n                    throw new ArchiveException(\n                        \"incompatible catalog file version \" + SemanticVersion.toString(version) +\n                        \", archive software is \" + SemanticVersion.toString(ArchiveMarkFile.SEMANTIC_VERSION));\n                }\n\n                alignment = catalogHeaderDecoder.alignment();\n                nextRecordingId = catalogHeaderDecoder.nextRecordingId();\n            }\n            else\n            {\n                alignment = CACHE_LINE_LENGTH;\n\n                catalogHeaderEncoder\n                    .version(ArchiveMarkFile.SEMANTIC_VERSION)\n                    .length(CatalogHeaderEncoder.BLOCK_LENGTH)\n                    .nextRecordingId(nextRecordingId)\n                    .alignment(alignment);\n\n                forceWrites(archiveDirChannel);","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Catalog.java#L190-L226","documentation":"When opening an existing catalog file, Catalog verifies the recorded version's major version matches ArchiveMarkFile.MAJOR_VERSION. If an older/newer archive software wrote the catalog with a different major version, opening it is refused with this ArchiveException because the on-disk format is incompatible.","triggerScenarios":"Constructing a Catalog (directly or via Archive launch/ArchiveTool) against an existing catalog file whose header version major differs from the running library's ArchiveMarkFile.MAJOR_VERSION, with no versionCheck override on this path.","commonSituations":"Upgrading or downgrading Aeron across a major version and reusing the old archive directory; running a newer ArchiveTool against an archive produced by an older cluster; mixing archive component versions in the same deployment.","solutions":["Align the archive software version with the version that wrote the catalog (major version must match).","Back up the archive directory, then migrate/recreate the catalog with a compatible tool version.","If intentional, use the Catalog constructor that accepts a custom versionCheck to permit the version."],"exampleFix":"// before: opening an old catalog with a newer incompatible library\nArchive archive = Archive.launch(configWithArchiveDir(\"/var/aeron/archive\")); // throws\n// after: run the archive with the same major version that created the catalog\n// or supply a versionCheck that accepts the stored version:\nnew Catalog(archiveDir, clock, null, fileSyncLevel, (version) -> true, wirePool);","handlingStrategy":"validation","validationCode":"// Check catalog version before opening\nfinal int version = readCatalogHeaderVersion(archiveDir);\nif (SemanticVersion.major(version) != ArchiveMarkFile.MAJOR_VERSION) {\n    throw new IllegalStateException(\"catalog major version \" + SemanticVersion.toString(version) +\n        \" incompatible with archive software \" + SemanticVersion.toString(ArchiveMarkFile.SEMANTIC_VERSION));\n}","typeGuard":null,"tryCatchPattern":"try {\n    catalog = new Catalog(archiveDir, clock, null, fileSyncLevel, wirePool);\n} catch (ArchiveException e) {\n    if (e.getMessage().startsWith(\"incompatible catalog file version\")) {\n        // switch to a compatible library version or migrate the archive\n    } else { throw e; }\n}","preventionTips":["Pin one Aeron version across all services that share an archive directory.","Back up the archive directory before upgrading Aeron major versions.","Check release notes for catalog format (major version) changes before upgrading."],"tags":["aeron-archive","catalog","version-mismatch","upgrade"],"backgroundTag":"incompatible-source-type","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}