{"record":{"id":"a6337eb5361f47c6","repo":"aeron-io/aeron","slug":"default-header-length-not-equal-to-header-length-length","errorCode":null,"errorMessage":"Default header length not equal to HEADER_LENGTH: length={capacity}","messagePattern":"Default header length not equal to HEADER_LENGTH: length=(.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/logbuffer/LogBufferDescriptor.java","lineNumber":841,"sourceCode":"     * @return the total length of the log file.\n     */\n    public static long computeLogLength(final int termLength, final int filePageSize)\n    {\n        return align((PARTITION_COUNT * (long)termLength) + LOG_META_DATA_LENGTH, filePageSize);\n    }\n\n    /**\n     * Store the default frame header to the log metadata buffer.\n     *\n     * @param metadataBuffer into which the default headers should be stored.\n     * @param defaultHeader  to be stored.\n     * @throws IllegalArgumentException if the defaultHeader larger than {@link #LOG_DEFAULT_FRAME_HEADER_MAX_LENGTH}.\n     */\n    public static void storeDefaultFrameHeader(final UnsafeBuffer metadataBuffer, final DirectBuffer defaultHeader)\n    {\n        if (defaultHeader.capacity() != HEADER_LENGTH)\n        {\n            throw new IllegalArgumentException(\n                \"Default header length not equal to HEADER_LENGTH: length=\" + defaultHeader.capacity());\n        }\n\n        metadataBuffer.putInt(LOG_DEFAULT_FRAME_HEADER_LENGTH_OFFSET, HEADER_LENGTH);\n        metadataBuffer.putBytes(LOG_DEFAULT_FRAME_HEADER_OFFSET, defaultHeader, 0, HEADER_LENGTH);\n    }\n\n    /**\n     * Get a wrapper around the default frame header from the log metadata.\n     *\n     * @param metadataBuffer containing the raw bytes for the default frame header.\n     * @return a buffer wrapping the raw bytes.\n     */\n    public static UnsafeBuffer defaultFrameHeader(final UnsafeBuffer metadataBuffer)\n    {\n        return new UnsafeBuffer(metadataBuffer, LOG_DEFAULT_FRAME_HEADER_OFFSET, HEADER_LENGTH);\n    }\n","sourceCodeStart":823,"sourceCodeEnd":859,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/logbuffer/LogBufferDescriptor.java#L823-L859","documentation":"storeDefaultFrameHeader copies the per-publication default frame header into the log metadata buffer, and it must be exactly HEADER_LENGTH (32 bytes on Aeron) long. When defaultHeader.capacity() differs, an IllegalArgumentException is thrown because a wrong-sized header would corrupt the framing of every data frame written to the log.","triggerScenarios":"Calling LogBufferDescriptor.storeDefaultFrameHeader with a DirectBuffer whose capacity is not HEADER_LENGTH (e.g. 36 or 24 bytes), typically when constructing a custom default header for a Publication or when allocating the header buffer with the wrong constant.","commonSituations":"Custom protocol/instance-id headers built with DataHeaderFlyweight but sized incorrectly, refactoring that changed HEADER_LENGTH assumptions between Aeron versions, or manually sized UnsafeBuffer allocations.","solutions":["Allocate the default header buffer with exactly LogBufferDescriptor.HEADER_LENGTH capacity (e.g. new UnsafeBuffer(ByteBuffer.allocateDirect(LogBufferDescriptor.HEADER_LENGTH)))","Build the header via DataHeaderFlyweight.DEFAULT_HEADER_DEFAULT or DataHeaderFlyweight.createDefaultHeader(...) which produce correctly sized buffers","Check defaultHeader.capacity() == LogBufferDescriptor.HEADER_LENGTH before calling storeDefaultFrameHeader"],"exampleFix":"// before\nfinal UnsafeBuffer header = new UnsafeBuffer(new byte[64]);\nLogBufferDescriptor.storeDefaultFrameHeader(metaBuffer, header);\n// after\nfinal UnsafeBuffer header = new UnsafeBuffer(ByteBuffer.allocateDirect(LogBufferDescriptor.HEADER_LENGTH));\nLogBufferDescriptor.storeDefaultFrameHeader(metaBuffer, header);","handlingStrategy":"validation","validationCode":"if (defaultHeader.capacity() != LogBufferDescriptor.HEADER_LENGTH) { throw new IllegalArgumentException(\"default header must be HEADER_LENGTH=\" + LogBufferDescriptor.HEADER_LENGTH); }","typeGuard":null,"tryCatchPattern":"try { LogBufferDescriptor.storeDefaultFrameHeader(metaBuffer, defaultHeader); } catch (final IllegalArgumentException ex) { if (ex.getMessage().startsWith(\"Default header length not equal\")) { /* rebuild header via DataHeaderFlyweight */ } throw ex; }","preventionTips":["Always build default headers with DataHeaderFlyweight.createDefaultHeader(...)","Reference LogBufferDescriptor.HEADER_LENGTH instead of hard-coded sizes","Re-check header construction after Aeron version upgrades"],"tags":["aeron","log-buffer","framing","validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}