pinpoint-apm/pinpoint · error · StringIndexOutOfBoundsException

String is longer then target length of bytes.

Error message

String is longer then target length of bytes.

What it means

BytesUtils.toFixedLengthBytes converts a string to a fixed-length byte array by copying its UTF-8/encoded bytes into a buffer of the requested length. If the encoded string is longer than the target length, the copy would truncate data, so it throws StringIndexOutOfBoundsException instead of silently truncating.

Solutions

1. Shorten the input string so its encoded byte length fits the target length.
2. Truncate explicitly before calling, accounting for multibyte characters (truncate on bytes, not chars).
3. Increase the fixed length if the schema allows longer values.

Example fix

// before
byte[] fixed = BytesUtils.toFixedLengthBytes(agentName, 24);
// after
String safe = agentName;
while (safe.getBytes(StandardCharsets.UTF_8).length > 24) {
    safe = safe.substring(0, safe.length() - 1);
}
byte[] fixed = BytesUtils.toFixedLengthBytes(safe, 24);

int byteLen = str.getBytes(StandardCharsets.UTF_8).length;
if (byteLen > length) {
    throw new IllegalArgumentException("string needs " + byteLen + " bytes, limit " + length);
}

boolean fitsFixedLength(String s, int len) { return s == null || s.getBytes(StandardCharsets.UTF_8).length <= len; }

try {
    return BytesUtils.toFixedLengthBytes(str, length);
} catch (StringIndexOutOfBoundsException e) {
    log.warn("Value too long for fixed field ({} bytes max)", length);
    return truncateToBytes(str, length);
}

When it happens

Trigger: Calling BytesUtils.toFixedLengthBytes(str, length) where str's encoded byte length exceeds length, e.g. toFixedLengthBytes("agent-long-name-1234567890", 24) or multibyte characters inflating byte length beyond the limit.

Common situations: Writing Pinpoint fixed-width storage fields (agent name, application name) with values longer than the schema's fixed byte size, or non-ASCII names where byte length exceeds character length assumptions.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• UnsignedByte Out of Range (0~255)

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

Appendix: source

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

        System.arraycopy(data, 0, buf, 1, data.length);
        return buf;
    }

    public static byte[] toBytes(final String value) {
        return value == null ? null : value.getBytes(UTF8_CHARSET);
    }

    public static byte[] toFixedLengthBytes(final String str, final int length) {
        if (length < 0) {
            throw new ArrayIndexOutOfBoundsException(length);
        }
        final byte[] b1 = toBytes(str);
        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);
    }

View on GitHub (pinned to 744c3d3075)