MyCATApache/Mycat-Server · error · IOException

Tried to send an out-of-range integer as a 2-byte value

Error message

Tried to send an out-of-range integer as a 2-byte value: ${val}

What it means

PIOUtils.SendInteger2() encodes an int as a PostgreSQL protocol Int16 (2-byte) value. If val is below Short.MIN_VALUE (-32768) or above Short.MAX_VALUE (32767), it throws an IOException stating the integer is out of range for a 2-byte field.

Solutions

1. Use SendInteger4/SendInteger8 for values that can exceed 32767 instead of SendInteger2
2. Clamp or validate the value against Short range before calling SendInteger2 and choose the correct width dynamically
3. Check the PostgreSQL protocol spec for the field being written to confirm the required width
4. If it comes from computed data (counts/lengths), log the value and fix the upstream computation that produced the oversized number

Example fix

// before
PIOUtils.SendInteger2(paramCount, buffer);
// after
if (paramCount > Short.MAX_VALUE) { PIOUtils.SendInteger4(paramCount, buffer); } else { PIOUtils.SendInteger2(paramCount, buffer); }

if (val < Short.MIN_VALUE || val > Short.MAX_VALUE) {
    throw new IllegalArgumentException("value " + val + " needs SendInteger4/8, not SendInteger2");
}
PIOUtils.SendInteger2(val, buffer);

boolean fitsInt16(int v) { return v >= Short.MIN_VALUE && v <= Short.MAX_VALUE; }

try { writePacket(...); } catch (IOException e) { if (e.getMessage().startsWith("Tried to send an out-of-range integer")) { /* use wider writer or clamp */ } else { throw e; } }

When it happens

Trigger: Calling SendInteger2 (directly or via packet builders) with a value >32767 or <-32768 — e.g. an oversized protocol field such as a parameter count, port-like field, or message length component passed to the wrong writer.

Common situations: Custom packet construction with wrong-width writer (using SendInteger2 where SendInteger4 is required); large column/parameter counts overflowing 2 bytes; protocol corruption feeding computed lengths into Int16 fields.

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

• the select proess err ,the SelectResponse is empty
• Unknown packet
• Unknown Packet!
• unknown status!
• txIsolation

AI-assisted analysis of MyCATApache/Mycat-Server@65f8d8beb7 (2026-09-11). Data as JSON: /api/errors/cfe8e48c76711b22. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/io/mycat/backend/postgresql/utils/PIOUtils.java:61

	 * @return
	 */
	public static short redInteger2(ByteBuffer buffer, int offset) {
		return buffer.getShort(offset);
	}

	/**
	 * Sends a 2-byte integer (short) to the back end
	 *
	 * @param val
	 *            the integer to be sent
	 * @exception IOException
	 *                if an I/O error occurs or <code>val</code> cannot be
	 *                encoded in 2 bytes
	 */
	public static void SendInteger2(int val, ByteBuffer buffer)
			throws IOException {
		if (val < Short.MIN_VALUE || val > Short.MAX_VALUE) {
			throw new IOException(
					"Tried to send an out-of-range integer as a 2-byte value: "
							+ val);
		}

		byte[] _int2buf = new byte[2];
		_int2buf[0] = (byte) (val >>> 8);
		_int2buf[1] = (byte) val;
		buffer.put(_int2buf);
	}

	public static void Send(byte[] encodedParam, ByteBuffer buffer) {
		buffer.put(encodedParam);
	}

	public static void SendChar(int i, ByteBuffer buffer) {
		buffer.put((byte) i);
	}

View on GitHub (pinned to 65f8d8beb7)