netty/netty · error · IllegalArgumentException

inconsistent byte order

Error message

inconsistent byte order

What it means

Thrown by Unpooled.copiedBuffer(ByteBuf... buffers) when buffers disagree on byte order (endianness). Netty records the first buffer's order() and compares each subsequent buffer against it; any mismatch (e.g. mixing BIG_ENDIAN and LITTLE_ENDIAN) aborts the merge because a single backing array cannot represent mixed endianness coherently.

Source

Thrown at buffer/src/main/java/io/netty/buffer/Unpooled.java:495

            return copiedBuffer(buffers[0]);
        }

        // Merge the specified buffers into one buffer.
        ByteOrder order = null;
        int length = 0;
        for (ByteBuf b: buffers) {
            int bLen = b.readableBytes();
            if (bLen <= 0) {
                continue;
            }
            if (Integer.MAX_VALUE - length < bLen) {
                throw new IllegalArgumentException(
                        "The total length of the specified buffers is too big.");
            }
            length += bLen;
            if (order != null) {
                if (!order.equals(b.order())) {
                    throw new IllegalArgumentException("inconsistent byte order");
                }
            } else {
                order = b.order();
            }
        }

        if (length == 0) {
            return EMPTY_BUFFER;
        }

        byte[] mergedArray = PlatformDependent.allocateUninitializedArray(length);
        for (int i = 0, j = 0; i < buffers.length; i ++) {
            ByteBuf b = buffers[i];
            int bLen = b.readableBytes();
            b.getBytes(b.readerIndex(), mergedArray, j, bLen);
            j += bLen;
        }

View on GitHub (pinned to 70040aacae)

Solutions

1. Normalize endianness before merging: call buf.order(ByteOrder.BIG_ENDIAN) (or a single chosen order) on every input.
2. Convert each buffer's bytes to a canonical order before copiedBuffer.
3. Operate on raw byte[] via copiedBuffer(byte[]...) which has no endianness concept.

Example fix

// before
ByteBuf out = Unpooled.copiedBuffer(bigEndianBuf, littleEndianBuf);

// after
ByteBuf out = Unpooled.copiedBuffer(
    bigEndianBuf.retain(),
    littleEndianBuf.order(ByteOrder.BIG_ENDIAN));

ByteOrder target = ByteOrder.BIG_ENDIAN;
for (ByteBuf b : buffers) {
    if (!target.equals(b.order())) {
        b = b.order(target); // or reject
    }
}
ByteBuf out = Unpooled.copiedBuffer(buffers);

static boolean consistentOrder(ByteBuf... bufs) {
    ByteOrder ref = null;
    for (ByteBuf b : bufs) {
        if (ref == null) ref = b.order();
        else if (!ref.equals(b.order())) return false;
    }
    return true;
}

When it happens

Trigger: Mixing ByteBufs of different endianness in one copiedBuffer call, e.g. one wrapped with .order(LITTLE_ENDIAN) and others left default BIG_ENDIAN.

Common situations: Interfacing with protocols having different byte orders (some legacy binary protocols are little-endian); merging buffers produced by different codecs each setting order() explicitly.

Related errors

• All ByteBufs need to have same ByteOrder
• The total length of the specified arrays is too big.
• The total length of the specified buffers is too big.
• maxNumComponents: {maxNumComponents} (expected: >= 1)
• freeSweepAllocationThreshold: {} (expected: > 0)

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