netty/netty · error · IndexOutOfBoundsException

cIndex: %d (expected: >= 0 && <= numComponents(%d))

Error message

cIndex: %d (expected: >= 0 && <= numComponents(%d))

What it means

Thrown by CompositeByteBuf.checkComponentIndex(int cIndex) when cIndex is negative or greater than componentCount. It is an IndexOutOfBoundsException guarding insertion/retrieval by component index. Valid insertion points are 0..componentCount inclusive (appending at componentCount is allowed).

Source

Thrown at buffer/src/main/java/io/netty/buffer/CompositeByteBuf.java:578

    }

    /**
     * This should only be called as last operation from a method as this may adjust the underlying
     * array of components and so affect the index etc.
     */
    private void consolidateIfNeeded() {
        // Consolidate if the number of components will exceed the allowed maximum by the current
        // operation.
        int size = componentCount;
        if (size > maxNumComponents) {
            consolidate0(0, size);
        }
    }

    private void checkComponentIndex(int cIndex) {
        ensureAccessible();
        if (cIndex < 0 || cIndex > componentCount) {
            throw new IndexOutOfBoundsException(String.format(
                    "cIndex: %d (expected: >= 0 && <= numComponents(%d))",
                    cIndex, componentCount));
        }
    }

    private void checkComponentIndex(int cIndex, int numComponents) {
        ensureAccessible();
        if (cIndex < 0 || cIndex + numComponents > componentCount) {
            throw new IndexOutOfBoundsException(String.format(
                    "cIndex: %d, numComponents: %d " +
                    "(expected: cIndex >= 0 && cIndex + numComponents <= totalNumComponents(%d))",
                    cIndex, numComponents, componentCount));
        }
    }

    private void updateComponentOffsets(int cIndex) {
        int size = componentCount;
        if (size <= cIndex) {

View on GitHub (pinned to 70040aacae)

Solutions

1. Query the live count right before use: int n = comp.numComponents(); add at n to append.
2. Prefer the append overloads addComponent(buffer) / addComponents(buffer...) which handle indexing for you.
3. Synchronize external access to a shared composite or give each thread its own.

Example fix

// before
comp.addComponent(true, cachedCount, buf); // cachedCount may be stale

// after
comp.addComponent(true, comp.numComponents(), buf); // safe append

static void addAt(CompositeByteBuf comp, int cIndex, ByteBuf buf) {
    if (cIndex < 0 || cIndex > comp.numComponents()) {
        cIndex = comp.numComponents(); // append
    }
    comp.addComponent(true, cIndex, buf);
}

null

null

When it happens

Trigger: Calling addComponent(increaseWriterIndex, cIndex, buffer) or any cIndex-based API with cIndex < 0 or cIndex > componentCount, e.g. using an offset past the end or a stale count after concurrent removal.

Common situations: Storing componentCount before adding components and reusing it; treating component indices as 0-based past-the-end; concurrent pipeline threads mutating one composite.

Related errors

• cIndex: %d, numComponents: %d (expected: cIndex >= 0 && cInd
• expected: 0 <= offset({offset}) <= offset + length({length})
• index: {index} length: {length}
• maxNumComponents: {maxNumComponents} (expected: >= 1)
• Can't increase by {readableBytes} as capacity({capacity}) wo

AI-assisted analysis of netty/netty@70040aacae (2026-08-14). Data as JSON: /api/errors/88a55b96963ec3d7. Report an issue: GitHub.