{"record":{"id":"afb452a24f67195c","repo":"aeron-io/aeron","slug":"existing-mark-file-type-existingtype-not-same-as-required","errorCode":null,"errorMessage":"existing Mark file type <existingType> not same as required type <type>","messagePattern":"existing Mark file type <existingType> not same as required type <type>","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"critical","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/service/ClusterMarkFile.java","lineNumber":191,"sourceCode":"                null);\n            final UnsafeBuffer existingBuffer = existingMarkFile.buffer();\n\n            if (0 != currentHeaderOffset)\n            {\n                headerDecoder.wrapAndApplyHeader(existingBuffer, 0, messageHeaderDecoder);\n            }\n            else\n            {\n                headerDecoder.wrap(\n                    existingBuffer, 0, MarkFileHeaderDecoder.BLOCK_LENGTH, MarkFileHeaderDecoder.SCHEMA_VERSION);\n            }\n\n            final ClusterComponentType existingType = headerDecoder.componentType();\n            if (existingType != ClusterComponentType.UNKNOWN && existingType != type)\n            {\n                if (existingType != ClusterComponentType.BACKUP || ClusterComponentType.CONSENSUS_MODULE != type)\n                {\n                    throw new ClusterException(\n                        \"existing Mark file type \" + existingType + \" not same as required type \" + type);\n                }\n            }\n\n            final int existingErrorBufferLength = headerDecoder.errorBufferLength();\n            final int headerLength = headerDecoder.headerLength();\n            final UnsafeBuffer existingErrorBuffer =\n                new UnsafeBuffer(existingBuffer, headerLength, existingErrorBufferLength);\n\n            saveExistingErrors(file, existingErrorBuffer, type, CommonContext.fallbackLogger());\n            existingErrorBuffer.setMemory(0, existingErrorBufferLength, (byte)0);\n\n            candidateTermId = headerDecoder.candidateTermId();\n\n            if (0 != currentHeaderOffset)\n            {\n                markFile = existingMarkFile;\n                buffer = existingBuffer;","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/service/ClusterMarkFile.java#L173-L209","documentation":"When opening an existing ClusterMarkFile, the stored componentType in the header is compared with the required type (consensus module vs clustered service). A mismatch throws ClusterException, except the permitted case of an existing BACKUP file being reused as a CONSENSUS_MODULE. This guards against sharing one mark file between different cluster roles.","triggerScenarios":"Starting a clustered service with a serviceId whose mark file was previously created by a different component type (e.g. a consensus module writing to the same file), or pointing components at the same mark file path.","commonSituations":"Misconfigured clusterDir/serviceId reuse; copy-pasting mark files between roles; switching a process between consensus-module and service mode in the same directory.","solutions":["Use the correct, role-specific mark file: clustered services derive their filename from the serviceId (see ClusterMarkFile filename helper); ensure serviceId differs per role.","Point each component at its own cluster directory or remove/replace the incompatible mark file if the data is stale.","Verify you are not accidentally launching a consensus module with a service's mark file (BACKUP→CONSENSUS_MODULE is the only allowed reuse)."],"exampleFix":"// before\nClusterMarkFile markFile = new ClusterMarkFile(clusterDir, \"cluster-mark\", ...); // same file for service\n// after\nClusterMarkFile markFile = new ClusterMarkFile(clusterDir, ClusterMarkFile.filename(serviceId), ...); // role-specific file","handlingStrategy":"validation","validationCode":"// java: check the component type recorded in the file before constructing the real mark file\nClusterMarkFile.HeaderDecoder d = readHeaderDecoder(markFile); // your own SBE read of the file\nClusterComponentType existing = d.componentType();\nif (existing != ClusterComponentType.UNKNOWN && existing != requiredType &&\n    !(existing == ClusterComponentType.BACKUP && requiredType == ClusterComponentType.CONSENSUS_MODULE)) {\n    throw new IllegalStateException(\"mark file owned by \" + existing + \", need \" + requiredType);\n}","typeGuard":null,"tryCatchPattern":"try {\n    new ClusterMarkFile(file, type, ...);\n} catch (ClusterException e) {\n    if (e.getMessage().contains(\"not same as required type\")) {\n        // check serviceId/directory configuration before retrying\n    }\n    throw e;\n}","preventionTips":["Give every clustered service a distinct serviceId so each gets its own mark file.","Never copy mark files between consensus module, backup, and service roles.","Keep one cluster directory per role and document which component owns it."],"tags":["java","mark-file","configuration","component-type"],"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"}