What causes "UnsignedByte Out of Range (0~255)" in pinpoint-apm/pinpoint?

Clamp or mask the value to 0-255 before calling: value & 0xFF.

pinpoint-apm/pinpoint · error · IllegalArgumentException

UnsignedByte Out of Range (0~255)

Error message

UnsignedByte Out of Range (0~255)

What it means

BytesUtils.toUnsignedByte converts an int in the range 0-255 into a byte representing that unsigned value. Since Java bytes are signed, only ints within [UNSIGNED_BYTE_MIN=0, UNSIGNED_BYTE_MAX=255] can be represented; anything outside would silently wrap, so the method throws IllegalArgumentException.

Solutions

Clamp or mask the value to 0-255 before calling: value & 0xFF.
Use a larger primitive (short/int) or writeShort if the value legitimately needs more than 8 bits.
Fix the upstream computation producing the out-of-range value.

Example fix

// before
BytesUtils.writeUnsignedByte(buf, value);
// after
BytesUtils.writeUnsignedByte(buf, value & 0xFF);

Defensive patterns

Strategy: type-guard

Validate before calling

if (value < 0 || value > 255) {
    throw new IllegalArgumentException("unsigned byte value out of range: " + value);
}

Type guard

boolean isUnsignedByte(int v) { return v >= 0 && v <= 255; }

Try / catch

try {
    BytesUtils.writeUnsignedByte(buf, value);
} catch (IllegalArgumentException e) {
    log.warn("Value {} does not fit in one byte; using short", value);
    BytesUtils.writeShort(buf, value);
}

Prevention

Mask computed values with & 0xFF before byte serialization
Choose wider fields (short/int) when values can exceed 255
Add range assertions in serialization helper tests

When it happens

Trigger: Calling toUnsignedByte (directly or via writeUnsignedByte) with an int outside 0-255, e.g. writeUnsignedByte(300), a negative value like -1, or an unmasked int computation result exceeding 255.

Common situations: Serializing protocol fields with computed values (lengths, flags) that overflow a single byte, or passing signed values that were intended to be masked with & 0xff beforehand.

Related errors

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/b39b8882d14577a2. Report an issue: GitHub.

Appendix: source

Thrown at commons/src/main/java/com/navercorp/pinpoint/common/util/BytesUtils.java:568

        if (b1 == null) {
            return new byte[length];
        }

        if (b1.length > length) {
            throw new StringIndexOutOfBoundsException("String is longer then target length of bytes.");
        }
        byte[] b = new byte[length];
        System.arraycopy(b1, 0, b, 0, b1.length);

        return b;
    }

    /**
     * Range : 0 ~ 255
     */
    public static byte toUnsignedByte(int value) {
        if (value < UNSIGNED_BYTE_MIN || value > UNSIGNED_BYTE_MAX) {
            throw new IllegalArgumentException("UnsignedByte Out of Range (0~255)");
        }
        return (byte) (value & 0xff);
    }


    public static int intToZigZag(final int n) {
        return (n << 1) ^ (n >> 31);
    }

    public static int zigzagToInt(final int n) {
        return (n >>> 1) ^ -(n & 1);
    }


    public static long longToZigZag(final long n) {
        return (n << 1) ^ (n >> 63);
    }

View on GitHub (pinned to 744c3d3075)