{"record":{"id":"61db1fa6e829a90e","repo":"aeron-io/aeron","slug":"term-length-more-than-max-length-of-term-max-length-length","errorCode":null,"errorMessage":"Term length more than max length of {TERM_MAX_LENGTH}: length={termLength}","messagePattern":"Term length more than max length of (.+?): length=(.+?)","errorType":"validation","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/logbuffer/LogBufferDescriptor.java","lineNumber":462,"sourceCode":"    }\n\n    /**\n     * Check that term length is valid and alignment is valid.\n     *\n     * @param termLength to be checked.\n     * @throws IllegalStateException if the length is not as expected.\n     */\n    public static void checkTermLength(final int termLength)\n    {\n        if (termLength < TERM_MIN_LENGTH)\n        {\n            throw new IllegalStateException(\n                \"Term length less than min length of \" + TERM_MIN_LENGTH + \": length=\" + termLength);\n        }\n\n        if (termLength > TERM_MAX_LENGTH)\n        {\n            throw new IllegalStateException(\n                \"Term length more than max length of \" + TERM_MAX_LENGTH + \": length=\" + termLength);\n        }\n\n        if (!BitUtil.isPowerOfTwo(termLength))\n        {\n            throw new IllegalStateException(\"Term length not a power of 2: length=\" + termLength);\n        }\n    }\n\n    /**\n     * Check that page size is valid and alignment is valid.\n     *\n     * @param pageSize to be checked.\n     * @throws IllegalStateException if the size is not as expected.\n     */\n    public static void checkPageSize(final int pageSize)\n    {\n        if (pageSize < PAGE_MIN_SIZE)","sourceCodeStart":444,"sourceCodeEnd":480,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/logbuffer/LogBufferDescriptor.java#L444-L480","documentation":"Aeron's LogBufferDescriptor.checkTermLength validates that a term buffer length is within the allowed range before a log buffer is created or mapped. This error means the supplied termLength exceeds TERM_MAX_LENGTH (1GB in Aeron), which the transport does not support because term buffers are addressed with a fixed-bit offset scheme. It is thrown as IllegalStateException during channel/subscription configuration.","triggerScenarios":"Calling Aeron.addPublication/addSubscription (or configuring a channel) with 'term-length' URI parameter, or Aeron.Context setting, greater than 1073741824 (1GB); programmatically passing termLength > TERM_MAX_LENGTH to checkTermLength or log buffer allocation code.","commonSituations":"Users naively raising term-length hoping to increase throughput (e.g. setting 2GB), copying a config from documentation with a typo like term-length=4294967296, or generating channel URIs programmatically with an unbounded value.","solutions":["Reduce the term-length URI parameter (or Context termBufferLength) to at most 1073741824 (1GB), e.g. aeron.uri()?term-length=1073741824","Use a power-of-two value within the supported range (64KB–1GB) and verify with BitUtil.isPowerOfTwo and LogBufferDescriptor.TERM_MAX_LENGTH before use","If more buffering is needed, increase IPC/publication termBufferMaxLength at the driver level within limits, or split traffic across multiple channels instead of one giant term buffer"],"exampleFix":"// before\nfinal ChannelUri uri = ChannelUri.create(ctx, \"aeron:udp?endpoint=localhost:40456|term-length=2147483648\");\n// after\nfinal ChannelUri uri = ChannelUri.create(ctx, \"aeron:udp?endpoint=localhost:40456|term-length=1073741824\");","handlingStrategy":"validation","validationCode":"if (termLength > LogBufferDescriptor.TERM_MAX_LENGTH || termLength < LogBufferDescriptor.TERM_MIN_LENGTH)\n{\n    throw new IllegalArgumentException(\"term-length must be between \" + LogBufferDescriptor.TERM_MIN_LENGTH + \" and \" + LogBufferDescriptor.TERM_MAX_LENGTH);\n}","typeGuard":null,"tryCatchPattern":"try { publication = aeron.addPublication(channel, streamId); } catch (final IllegalStateException ex) { if (ex.getMessage().contains(\"Term length more than max\")) { /* fix channel URI config */ } throw ex; }","preventionTips":["Clamp term-length config to [TERM_MIN_LENGTH, TERM_MAX_LENGTH] at config load time","Never set term-length above 1GB; tune throughput via driver-level options instead","Log the effective channel URI after building it so bad values are visible"],"tags":["aeron","configuration","term-buffer","validation"],"backgroundTag":"value-out-of-range","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"}