{"record":{"id":"2ed720323ac55ce1","repo":"aeron-io/aeron","slug":"assumed-term-length-does-not-match-metadata-termlength","errorCode":null,"errorMessage":"assumed term length  does not match metadata: termLength=","messagePattern":"assumed term length  does not match metadata: termLength=","errorType":"validation","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/LogBuffers.java","lineNumber":146,"sourceCode":"\n                final MappedByteBuffer metaDataMappedBuffer = fileChannel.map(\n                    mapMode, metaDataSectionOffset, metaDataMappingLength);\n                metaDataMappedBuffer.order(ByteOrder.LITTLE_ENDIAN);\n\n                mappedByteBuffers[LOG_META_DATA_SECTION_INDEX] = metaDataMappedBuffer;\n\n                logMetaDataBuffer = new UnsafeBuffer(\n                    metaDataMappedBuffer,\n                    (int)metaDataMappingLength - LOG_META_DATA_LENGTH,\n                    LOG_META_DATA_LENGTH);\n\n                final int metaDataTermLength = LogBufferDescriptor.termLength(logMetaDataBuffer);\n                final int pageSize = LogBufferDescriptor.pageSize(logMetaDataBuffer);\n\n                checkPageSize(pageSize);\n                if (metaDataTermLength != assumedTermLength)\n                {\n                    throw new IllegalStateException(\n                        \"assumed term length \" + assumedTermLength +\n                        \" does not match metadata: termLength=\" + metaDataTermLength);\n                }\n\n                termLength = assumedTermLength;\n\n                for (int i = 0; i < PARTITION_COUNT; i++)\n                {\n                    final long position = assumedTermLength * (long)i;\n                    final MappedByteBuffer mappedBuffer = fileChannel.map(mapMode, position, assumedTermLength);\n                    mappedBuffer.order(ByteOrder.LITTLE_ENDIAN);\n                    mappedByteBuffers[i] = mappedBuffer;\n                    termBuffers[i] = mappedBuffer;\n                }\n            }\n        }\n        catch (final Exception ex)\n        {","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/LogBuffers.java#L128-L164","documentation":"LogBuffers throws this IllegalStateException when the term length recorded in the log file's metadata buffer differs from the assumedTermLength the constructor was given. Aeron requires the mapped log's metadata to agree with the expected geometry; a mismatch means the file belongs to a different configuration or is corrupt.","triggerScenarios":"Reusing/replaying a log file created with a different aeron.term.length than the assumedTermLength passed to LogBuffers; attaching to a stale log from a previous run whose term length config changed; passing a wrong length constant when opening a read-only log.","commonSituations":"Changing term-length channel configuration between runs while reusing a persistent log directory; mixed client/library versions with different default term lengths pointing at the same log file; replay tools hard-coding a term length.","solutions":["Read the actual term length from the log metadata (LogBufferDescriptor.termLength on the metadata buffer) instead of assuming one, or pass a matching assumedTermLength.","Clear the stale log directory so a fresh log is created with the current configuration.","Make the channel term-length configuration consistent between the runs that produce and consume the log file."],"exampleFix":"// before\nLogBuffers buffers = new LogBuffers(file, 1 << 20 /* assumed 1MB term */);\n// after\nAtomicBuffer metaBuffer = LogBufferDescriptor.metaDataBuffer(map);\nint actualTermLength = LogBufferDescriptor.termLength(metaBuffer);\nLogBuffers buffers = new LogBuffers(file, actualTermLength);","handlingStrategy":"validation","validationCode":"int actualTermLength = LogBufferDescriptor.termLength(metaDataBuffer);\nif (assumedTermLength != actualTermLength) {\n    assumedTermLength = actualTermLength; // adopt metadata value\n}","typeGuard":null,"tryCatchPattern":"try {\n    return new LogBuffers(file, assumedTermLength);\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"assumed term length\")) {\n        return openWithMetadataTermLength(file); // re-read from metadata\n    }\n    throw e;\n}","preventionTips":["Never hard-code term lengths when opening logs; read them from metadata.","Keep aeron.term.length configuration stable across runs sharing a log directory.","Clear stale log directories after configuration changes."],"tags":["aeron","logbuffers","term-length","config-mismatch"],"backgroundTag":"invalid-config-value","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"}