{"record":{"id":"1b5ade30933890ef","repo":"aeron-io/aeron","slug":"difference-greater-than-2-31-1-initial-term-id-initialtermid","errorCode":null,"errorMessage":"difference greater than 2^31 - 1: initial-term-id={initialTermId} when term-id={termId} channel={channelUri}","messagePattern":"difference greater than 2\\^31 - 1: initial-term-id=(.+?) when term-id=(.+?) channel=(.+?)","errorType":"validation","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":148,"sourceCode":"                    TERM_LENGTH_PARAM_NAME + \"=\" + params.termLength + \": channel=\" + channelUri);\n            }\n\n            if (params.termOffset < 0 || params.termOffset > LogBufferDescriptor.TERM_MAX_LENGTH)\n            {\n                throw new InvalidChannelException(\n                    TERM_OFFSET_PARAM_NAME + \"=\" + params.termOffset + \" out of range: channel=\" + channelUri);\n            }\n\n            if (!FrameDescriptor.isFrameAligned(params.termOffset))\n            {\n                throw new InvalidChannelException(\n                    TERM_OFFSET_PARAM_NAME + \"=\" + params.termOffset +\n                    \" must be a multiple of FRAME_ALIGNMENT: channel=\" + channelUri);\n            }\n\n            if (params.termId - params.initialTermId < 0)\n            {\n                throw new InvalidChannelException(\n                    \"difference greater than 2^31 - 1: \" + INITIAL_TERM_ID_PARAM_NAME + \"=\" +\n                    params.initialTermId + \" when \" + TERM_ID_PARAM_NAME + \"=\" + params.termId + \" channel=\" +\n                    channelUri);\n            }\n\n            params.hasPosition = true;\n        }\n        else\n        {\n            params.initialTermId = BitUtil.generateRandomisedId();\n            params.termId = params.initialTermId;\n            params.termOffset = 0;\n        }\n\n        params.isResponse = CONTROL_MODE_RESPONSE.equals(channelUri.get(MDC_CONTROL_MODE_PARAM_NAME));\n        params.responseCorrelationId = parseResponseCorrelationId(channelUri);\n\n        return params;","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L130-L166","documentation":"The pair (initialTermId, termId) encodes how many terms the publication has advanced; termId - initialTermId must be non-negative when interpreted as a signed 32-bit difference. If the difference is negative the implied start position exceeds 2^31 - 1 terms, which Aeron rejects.","triggerScenarios":"A channel URI where termId is numerically less than initialTermId (e.g. initial-term-id=1|term-id=0), parsed in getPublicationParams.","commonSituations":"Computing termId = initialTermId + (position/termLength) with wraparound mishandled; using a raw session termId from an older stream as initialTermId; copying params between streams with different histories.","solutions":["Ensure termId - initialTermId is in [0, 2^31 - 1] by recomputing termId","Reset initialTermId to 0 and adjust termId accordingly","Remove the position-pinning params and let the publication start fresh"],"exampleFix":"// before\n\"aeron:udp?endpoint=...:40456|initial-term-id=5|term-id=3|term-offset=0\"\n// after\n\"aeron:udp?endpoint=...:40456|initial-term-id=3|term-id=5|term-offset=0\"","handlingStrategy":"validation","validationCode":"if (((termId - initialTermId) & 0xFFFFFFFFL) >= (1L << 31)) throw new IllegalArgumentException(\"termId too far from initialTermId\");","typeGuard":null,"tryCatchPattern":"try { pub = aeron.addPublication(uri, streamId); } catch (InvalidChannelException e) { log.error(\"term id range invalid: {}\", e.getMessage()); }","preventionTips":["Compute termId = initialTermId + (int)(position / termLength) with 64-bit math","Recompute position params when migrating streams between publications","Document term-id wraparound behavior in config tooling"],"tags":["aeron","uri","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-19T12:17:13.211Z"}