{"record":{"id":"ae646506505d1bec","repo":"aeron-io/aeron","slug":"mark-file-markfile-major-version-majorversion-does-not-match","errorCode":null,"errorMessage":"mark file (${markFile}) major version ${majorVersion} does not match software: ${MAJOR_VERSION}","messagePattern":"mark file \\((.+?)\\) major version (.+?) does not match software: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"aeron-archive/src/main/java/io/aeron/archive/ArchiveMarkFile.java","lineNumber":511,"sourceCode":"        headerEncoder\n            .startTimestamp(ctx.epochClock().time())\n            .controlStreamId(ctx.controlStreamId())\n            .localControlStreamId(ctx.localControlStreamId())\n            .eventsStreamId(ctx.recordingEventsStreamId())\n            .headerLength(HEADER_LENGTH)\n            .errorBufferLength(ctx.errorBufferLength())\n            .archiveId(ctx.archiveId())\n            .controlChannel(ctx.controlChannel())\n            .localControlChannel(ctx.localControlChannel())\n            .eventsChannel(ctx.recordingEventsChannel())\n            .aeronDirectory(ctx.aeronDirectoryName());\n    }\n\n    private static void validateVersion(final File markFile, final int version)\n    {\n        if (SemanticVersion.major(version) != MAJOR_VERSION)\n        {\n            throw new IllegalArgumentException(\n                \"mark file (\" + markFile.getAbsolutePath() + \") major version \" + SemanticVersion.major(version) +\n                \" does not match software: \" + MAJOR_VERSION);\n        }\n    }\n\n    private static int headerOffset(final File file)\n    {\n        final MappedByteBuffer mappedByteBuffer = IoUtil.mapExistingFile(file, FILENAME);\n        try\n        {\n            final UnsafeBuffer unsafeBuffer =\n                new UnsafeBuffer(mappedByteBuffer, 0, HEADER_OFFSET);\n            return headerOffset(unsafeBuffer);\n        }\n        finally\n        {\n            IoUtil.unmap(mappedByteBuffer);\n        }","sourceCodeStart":493,"sourceCodeEnd":529,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/ArchiveMarkFile.java#L493-L529","documentation":"ArchiveMarkFile.validateVersion throws IllegalArgumentException when the major version encoded in an existing archive mark file does not match the MAJOR_VERSION of the running Aeron Archive software. This guards against opening an archive produced by an incompatible release, which could corrupt metadata. It is a hard compatibility check performed whenever an existing mark file is opened.","triggerScenarios":"Opening an existing archive directory (via existingMarkFile -> ArchiveMarkFile) whose mark file's encoded major version differs from the software's MAJOR_VERSION, e.g. running a newer or older Aeron Archive against an archive dir created by an incompatible major release.","commonSituations":"Upgrading Aeron to a new major version while pointing at an old archive directory; pointing a downgraded archive client at an archive created by a newer version; sharing an archive dir between clusters running different Aeron versions.","solutions":["Check the Aeron version that created the archive directory (printMarkInformation / ArchiveTool describeRecording) and run a matching Archive version.","Upgrade the software to the major version matching the mark file, or migrate/export the archive with a compatible version before upgrading.","If the archive is disposable, delete or regenerate the mark file/catalog in a fresh archive directory."],"exampleFix":"// before\narchiveDir = new File(\"/data/old-archive\"); // created by Aeron 1.40, running 2.x -> throws\n// after\n// run Archive 1.40.x against /data/old-archive, or migrate the archive first","handlingStrategy":"validation","validationCode":"int markVersion = readMarkFileVersion(archiveDir); // read version from mark file header\nif (SemanticVersion.major(markVersion) != ArchiveMarkFile.MAJOR_VERSION) {\n    throw new IllegalStateException(\"archive major version \" + SemanticVersion.major(markVersion) +\n        \" != software \" + ArchiveMarkFile.MAJOR_VERSION);\n}","typeGuard":null,"tryCatchPattern":"try (ArchiveMarkFile markFile = ArchiveMarkFile.open(archiveDir, errHandler)) {\n    ...\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"major version\")) {\n        // fall back to a compatible Archive version or fail fast with a clear operator message\n    }\n}","preventionTips":["Pin the Aeron version used to write an archive and record it alongside the archive dir.","Check release notes for major version bumps before upgrading clusters with persistent archives.","Test archive compatibility in staging before rolling new Aeron versions to production.","Use ArchiveTool printMarkInformation to inspect the mark file version before opening with new software."],"tags":["aeron","archive","version-mismatch","compatibility"],"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-15T23:17:13.987Z"}