{"record":{"id":"c94453503cc86e96","repo":"netty/netty","slug":"decoder-properties-cannot-be-changed-once-the-deco","errorCode":null,"errorMessage":"decoder properties cannot be changed once the decoder is added to a pipeline.","messagePattern":"decoder properties cannot be changed once the decoder is added to a pipeline\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"codec-base/src/main/java/io/netty/handler/codec/MessageAggregator.java","lineNumber":185,"sourceCode":"\n    /**\n     * Sets the maximum number of components in the cumulation buffer.  If the number of\n     * the components in the cumulation buffer exceeds this value, the components of the\n     * cumulation buffer are consolidated into a single component, involving memory copies.\n     * The default value of this property is {@value #DEFAULT_MAX_COMPOSITEBUFFER_COMPONENTS}\n     * and its minimum allowed value is {@code 2}.\n     */\n    public final void setMaxCumulationBufferComponents(int maxCumulationBufferComponents) {\n        if (maxCumulationBufferComponents < 2) {\n            throw new IllegalArgumentException(\n                    \"maxCumulationBufferComponents: \" + maxCumulationBufferComponents +\n                    \" (expected: >= 2)\");\n        }\n\n        if (ctx == null) {\n            this.maxCumulationBufferComponents = maxCumulationBufferComponents;\n        } else {\n            throw new IllegalStateException(\n                    \"decoder properties cannot be changed once the decoder is added to a pipeline.\");\n        }\n    }\n\n    /**\n     * @deprecated This method will be removed in future releases.\n     */\n    @Deprecated\n    public final boolean isHandlingOversizedMessage() {\n        return handlingOversizedMessage;\n    }\n\n    protected final ChannelHandlerContext ctx() {\n        if (ctx == null) {\n            throw new IllegalStateException(\"not added to a pipeline yet\");\n        }\n        return ctx;\n    }","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/netty/netty/blob/70040aacae241e9ba371e758f5b86e470bd77ad1/codec-base/src/main/java/io/netty/handler/codec/MessageAggregator.java#L167-L203","documentation":"Decoder/aggregator tuning properties (like maxCumulationBufferComponents) may only be changed BEFORE the handler is added to the pipeline. Once ctx is set (handler added), setMaxCumulationBufferComponents throws IllegalStateException to prevent unsafe concurrent mutation during decoding.","triggerScenarios":"Calling aggregator.setMaxCumulationBufferComponents(...) after the aggregator was already added to a ChannelPipeline (ctx != null).","commonSituations":"Reconfiguring a shared handler instance at runtime; lazy-init code that configures after channel creation; hot-reloading config without recreating the handler; reusing a handler across channels.","solutions":["Set all properties before adding the handler to the pipeline (before bootstrap / channel setup).","Create a fresh handler instance per channel with the desired config instead of mutating a shared one.","If runtime change is required, replace the handler in the pipeline with a new configured instance."],"exampleFix":"// before\nch.pipeline().addLast(aggregator);\naggregator.setMaxCumulationBufferComponents(16); // throws\n\n// after\naggregator.setMaxCumulationBufferComponents(16);\nch.pipeline().addLast(aggregator);","handlingStrategy":"validation","validationCode":"// Configure BEFORE adding to pipeline:\naggregator.setMaxCumulationBufferComponents(n);\nassert pipeline.get(aggregator.getClass()) == null : \"handler already in pipeline\";","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set all decoder properties before pipeline.addLast(handler).","Create a new handler instance per channel rather than reconfiguring a shared one.","For runtime changes, swap the handler in the pipeline."],"tags":["netty","codec","aggregator","lifecycle","pipeline","configuration"],"backgroundTag":null,"analyzedSha":"70040aacae241e9ba371e758f5b86e470bd77ad1","analyzedAt":"2026-08-14T01:29:15.551Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}