{"record":{"id":"65e296081927e863","repo":"aeron-io/aeron","slug":"params-must-be-used-as-a-complete-set-initial-term-id-term","errorCode":null,"errorMessage":"params must be used as a complete set: initial-term-id term-id term-offset channel={channelUri}","messagePattern":"params must be used as a complete set: initial-term-id term-id term-offset channel=(.+?)","errorType":"validation","errorClass":"InvalidChannelException","httpStatus":null,"severity":"error","filePath":"aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java","lineNumber":117,"sourceCode":"        params.getUntetheredRestingTimeout(channelUri, ctx);\n        params.getMaxResend(channelUri, ctx);\n\n        int count = 0;\n\n        final String initialTermIdStr = channelUri.get(INITIAL_TERM_ID_PARAM_NAME);\n        count = initialTermIdStr != null ? count + 1 : count;\n\n        final String termIdStr = channelUri.get(TERM_ID_PARAM_NAME);\n        count = termIdStr != null ? count + 1 : count;\n\n        final String termOffsetStr = channelUri.get(TERM_OFFSET_PARAM_NAME);\n        count = termOffsetStr != null ? count + 1 : count;\n\n        if (count > 0)\n        {\n            if (count < 3)\n            {\n                throw new InvalidChannelException(\"params must be used as a complete set: \" +\n                    INITIAL_TERM_ID_PARAM_NAME + \" \" + TERM_ID_PARAM_NAME + \" \" + TERM_OFFSET_PARAM_NAME + \" channel=\" +\n                    channelUri);\n            }\n\n            params.initialTermId = parseInt(initialTermIdStr, INITIAL_TERM_ID_PARAM_NAME);\n            params.termId = parseInt(termIdStr, TERM_ID_PARAM_NAME);\n            params.termOffset = parseInt(termOffsetStr, TERM_OFFSET_PARAM_NAME);\n\n            if (params.termOffset > params.termLength)\n            {\n                throw new InvalidChannelException(\n                    TERM_OFFSET_PARAM_NAME + \"=\" + params.termOffset + \" > \" +\n                    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(","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-driver/src/main/java/io/aeron/driver/PublicationParams.java#L99-L135","documentation":"Aeron's initial-term-id, term-id and term-offset URI parameters must either all be absent or all present; they jointly pin a publication's start position. Supplying only some of the three makes the position under-specified, so an InvalidChannelException is thrown.","triggerScenarios":"Adding one or two of @initialTermId, termId, termOffset to a publication channel URI (e.g. only termId=0) when subscribing/adding the publication via Aeron.addPublication or client with those params.","commonSituations":"Hand-editing channel URIs for position-pinned publications; partial parameter propagation from config templates; mixing an old URI with new params when reproducing a session across restarts.","solutions":["Add all three params (initial-term-id, term-id, term-offset) to the channel URI","Remove all of them if position pinning is not intended","Build the URI programmatically with ChannelUri and set the full param triple"],"exampleFix":"// before\n\"aeron:udp?endpoint=224.0.1.1:40456|termId=0\"\n// after\n\"aeron:udp?endpoint=224.0.1.1:40456|initial-term-id=0|term-id=0|term-offset=0\"","handlingStrategy":"validation","validationCode":"int n = 0; for (String p : new String[]{\"initial-term-id\",\"term-id\",\"term-offset\"}) if (uri.contains(p)) n++; if (n > 0 && n < 3) throw new IllegalArgumentException(\"position params must be complete\");","typeGuard":null,"tryCatchPattern":"try { pub = aeron.addPublication(uri, streamId); } catch (InvalidChannelException e) { log.error(\"bad channel params: {}\", e.getMessage()); }","preventionTips":["Build URIs with ChannelUri.addParameter instead of string concatenation","Treat the three position params as one atomic unit in config","Lint channel URIs at startup"],"tags":["aeron","uri","validation"],"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-15T23:17:13.987Z"}