{"record":{"id":"b39b8882d14577a2","repo":"pinpoint-apm/pinpoint","slug":"unsignedbyte-out-of-range-0-255","errorCode":null,"errorMessage":"UnsignedByte Out of Range (0~255)","messagePattern":"UnsignedByte Out of Range \\(0~255\\)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"commons/src/main/java/com/navercorp/pinpoint/common/util/BytesUtils.java","lineNumber":568,"sourceCode":"        if (b1 == null) {\n            return new byte[length];\n        }\n\n        if (b1.length > length) {\n            throw new StringIndexOutOfBoundsException(\"String is longer then target length of bytes.\");\n        }\n        byte[] b = new byte[length];\n        System.arraycopy(b1, 0, b, 0, b1.length);\n\n        return b;\n    }\n\n    /**\n     * Range : 0 ~ 255\n     */\n    public static byte toUnsignedByte(int value) {\n        if (value < UNSIGNED_BYTE_MIN || value > UNSIGNED_BYTE_MAX) {\n            throw new IllegalArgumentException(\"UnsignedByte Out of Range (0~255)\");\n        }\n        return (byte) (value & 0xff);\n    }\n\n\n    public static int intToZigZag(final int n) {\n        return (n << 1) ^ (n >> 31);\n    }\n\n    public static int zigzagToInt(final int n) {\n        return (n >>> 1) ^ -(n & 1);\n    }\n\n\n    public static long longToZigZag(final long n) {\n        return (n << 1) ^ (n >> 63);\n    }\n","sourceCodeStart":550,"sourceCodeEnd":586,"githubUrl":"https://github.com/pinpoint-apm/pinpoint/blob/744c3d3075e595656abb1ae331ad2c0e4c9eb996/commons/src/main/java/com/navercorp/pinpoint/common/util/BytesUtils.java#L550-L586","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nBytesUtils.writeUnsignedByte(buf, value);\n// after\nBytesUtils.writeUnsignedByte(buf, value & 0xFF);","handlingStrategy":"type-guard","validationCode":"if (value < 0 || value > 255) {\n    throw new IllegalArgumentException(\"unsigned byte value out of range: \" + value);\n}","typeGuard":"boolean isUnsignedByte(int v) { return v >= 0 && v <= 255; }","tryCatchPattern":"try {\n    BytesUtils.writeUnsignedByte(buf, value);\n} catch (IllegalArgumentException e) {\n    log.warn(\"Value {} does not fit in one byte; using short\", value);\n    BytesUtils.writeShort(buf, value);\n}","preventionTips":["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"],"tags":["bytes","serialization","range-check","unsigned"],"backgroundTag":"argument-out-of-range","analyzedSha":"744c3d3075e595656abb1ae331ad2c0e4c9eb996","analyzedAt":"2026-09-07T18:48:45.289Z","contentChangedAt":"2026-09-07T18:48:45.289Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}