{"record":{"id":"254e93a3eafd37fc","repo":"aeron-io/aeron","slug":"difference-greater-than-2-31-1-initialtermid-initialtermid","errorCode":null,"errorMessage":"difference greater than 2^31 - 1: initialTermId=<initialTermId> when termId=<termId> channel=<channelUri>","messagePattern":"difference greater than 2\\^31 - 1: initialTermId=<initialTermId> when termId=<termId> channel=<channelUri>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/SubscriptionParams.java","lineNumber":104,"sourceCode":"            params.termId = Integer.parseInt(termIdStr);\n            params.termOffset = Integer.parseInt(termOffsetStr);\n\n            if (params.termOffset < 0 || params.termOffset > LogBufferDescriptor.TERM_MAX_LENGTH)\n            {\n                throw new IllegalArgumentException(\n                    TERM_OFFSET_PARAM_NAME + \"=\" + params.termOffset + \" out of range: channel=\" + channelUri);\n            }\n\n            if (!FrameDescriptor.isFrameAligned(params.termOffset))\n            {\n                throw new IllegalArgumentException(\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 IllegalStateException(\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.hasJoinPosition = true;\n        }\n\n        final String reliableStr = channelUri.get(RELIABLE_STREAM_PARAM_NAME);\n        params.isReliable = null != reliableStr ? \"true\".equals(reliableStr) : context.reliableStream();\n\n        final String rejoinStr = channelUri.get(REJOIN_PARAM_NAME);\n        params.isRejoin = null != rejoinStr ? \"true\".equals(rejoinStr) : context.rejoinStream();\n\n        final String tetherStr = channelUri.get(TETHER_PARAM_NAME);\n        params.isTether = null != tetherStr ? \"true\".equals(tetherStr) : context.tetherSubscriptions();\n\n        final String sparseStr = channelUri.get(SPARSE_PARAM_NAME);","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/SubscriptionParams.java#L86-L122","documentation":"The driver derives the join position from initialTermId and termId; if termId - initialTermId is negative the implied difference exceeds 2^31 - 1 and cannot be represented, so an IllegalStateException is thrown. This catches wrap-around arithmetic mistakes in the supplied position params.","triggerScenarios":"Subscription URI where termId is numerically less than initialTermId without a valid wrap, e.g. initial-term-id=100|term-id=50.","commonSituations":"Recomputing term ids after wrap incorrectly; mixing term ids recorded from different streams; hand-editing initial-term-id upward while leaving term-id stale.","solutions":["Ensure termId >= initialTermId (within int arithmetic) for the position you want.","Account for term wrap-around explicitly when computing ids from a position: termId = initialTermId + (int)(position / termLength).","Recompute all three params together from a recorded position rather than editing one in isolation."],"exampleFix":"// before\nuri += \"|initial-term-id=\" + initialTermId + \"|term-id=\" + currentTermId; // currentTermId wrapped below initialTermId\n// after\nint termId = initialTermId + (int)(position / termLength);\nuri += \"|initial-term-id=\" + initialTermId + \"|term-id=\" + termId + \"|term-offset=\" + termOffset;","handlingStrategy":"validation","validationCode":"if (termId - initialTermId < 0) {\n    throw new IllegalArgumentException(\"termId must be >= initialTermId (within 2^31 - 1)\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Compute termId = initialTermId + (int)(position / termLength) so wrap is handled.","Never hand-edit one of the three position params in isolation."],"tags":["aeron","subscription","arithmetic","config"],"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-16T04:17:20.429Z"}