apache/shardingsphere · error · UnsupportedSQLOperationException

Unsupported PostgreSQL format code `%s`

Error message

Unsupported PostgreSQL format code `%s`

What it means

Thrown by PostgreSQLValueFormat.valueOf(int) when a format code in a Bind/Describe message is not 0 (TEXT) or 1 (BINARY). The PostgreSQL protocol defines only these two format codes, so any other value means the client sent a malformed message or the stream is desynchronized.

Source

Thrown at database/protocol/dialect/postgresql/src/main/java/org/apache/shardingsphere/database/protocol/postgresql/constant/PostgreSQLValueFormat.java:51

    BINARY(1);
    
    private final int code;
    
    /**
     * Value of.
     *
     * @param code format code
     * @return PostgreSQL value format
     * @throws UnsupportedSQLOperationException unsupported SQL operation exception
     */
    public static PostgreSQLValueFormat valueOf(final int code) {
        switch (code) {
            case 0:
                return TEXT;
            case 1:
                return BINARY;
            default:
                throw new UnsupportedSQLOperationException(String.format("Unsupported PostgreSQL format code `%s`", code));
        }
    }
}

View on GitHub (pinned to e952770a21)

Solutions

1. Log the offending code and the preceding message bytes; codes like 2+ indicate framing misalignment rather than intent
2. Validate the client library is a standard PostgreSQL driver (psycopg, pgjdbc, libpq) at a current version
3. Reproduce with psql; if psql works, debug the custom client's Bind message construction
4. Ensure any custom client writes format codes as int16 network byte order with values 0 or 1 only

Example fix

# before: custom client sends invalid format code
pg_send_bytes(conn, struct.pack("!h", 2))  # invalid

# after: send a defined format code
pg_send_bytes(conn, struct.pack("!h", 1))  # BINARY

// when building a Bind message, restrict format codes to 0/1 before serializing
boolean ok = formatCodes.stream().allMatch(c -> c == 0 || c == 1);
if (!ok) {
    throw new IllegalArgumentException("format codes must be 0 (text) or 1 (binary)");
}
PostgreSQLValueFormat.valueOf(code); // now safe

static boolean isValidPgFormatCode(final int code) {
    return code == 0 || code == 1;
}

try {
    PostgreSQLValueFormat.valueOf(code);
} catch (UnsupportedSQLOperationException ex) {
    // invalid wire data: terminate the connection; format codes outside 0/1 cannot be recovered mid-message
    connection.closeDueToProtocolError(ex);
}

When it happens

Trigger: Sending an extended-protocol Bind message with a format code other than 0/1 in the parameter-format-codes or result-format-codes arrays; also hit when the proxy's reader is misaligned and consumes a stray byte as a format code.

Common situations: Hand-written PostgreSQL clients with wrong int16 format codes; a broken driver or proxy corrupting message framing; rarely, a server/fork extending format codes.

Related errors

• Connection [%s] is not registered.
• BLR is too short: %s
• Invalid batch handle: statement handle %d
• Can not find `%s` in PostgreSQL command packet type.
• Can not find value `%s` in PostgreSQL column type.

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/066fa01c3852bc42. Report an issue: GitHub.