{"record":{"id":"066fa01c3852bc42","repo":"apache/shardingsphere","slug":"unsupported-postgresql-format-code-s","errorCode":null,"errorMessage":"Unsupported PostgreSQL format code `%s`","messagePattern":"Unsupported PostgreSQL format code `(.+?)`","errorType":"exception","errorClass":"UnsupportedSQLOperationException","httpStatus":null,"severity":"error","filePath":"database/protocol/dialect/postgresql/src/main/java/org/apache/shardingsphere/database/protocol/postgresql/constant/PostgreSQLValueFormat.java","lineNumber":51,"sourceCode":"    BINARY(1);\n    \n    private final int code;\n    \n    /**\n     * Value of.\n     *\n     * @param code format code\n     * @return PostgreSQL value format\n     * @throws UnsupportedSQLOperationException unsupported SQL operation exception\n     */\n    public static PostgreSQLValueFormat valueOf(final int code) {\n        switch (code) {\n            case 0:\n                return TEXT;\n            case 1:\n                return BINARY;\n            default:\n                throw new UnsupportedSQLOperationException(String.format(\"Unsupported PostgreSQL format code `%s`\", code));\n        }\n    }\n}\n","sourceCodeStart":33,"sourceCodeEnd":55,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/database/protocol/dialect/postgresql/src/main/java/org/apache/shardingsphere/database/protocol/postgresql/constant/PostgreSQLValueFormat.java#L33-L55","documentation":"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.","triggerScenarios":"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.","commonSituations":"Hand-written PostgreSQL clients with wrong int16 format codes; a broken driver or proxy corrupting message framing; rarely, a server/fork extending format codes.","solutions":["Log the offending code and the preceding message bytes; codes like 2+ indicate framing misalignment rather than intent","Validate the client library is a standard PostgreSQL driver (psycopg, pgjdbc, libpq) at a current version","Reproduce with psql; if psql works, debug the custom client's Bind message construction","Ensure any custom client writes format codes as int16 network byte order with values 0 or 1 only"],"exampleFix":"# before: custom client sends invalid format code\npg_send_bytes(conn, struct.pack(\"!h\", 2))  # invalid\n\n# after: send a defined format code\npg_send_bytes(conn, struct.pack(\"!h\", 1))  # BINARY","handlingStrategy":"validation","validationCode":"// when building a Bind message, restrict format codes to 0/1 before serializing\nboolean ok = formatCodes.stream().allMatch(c -> c == 0 || c == 1);\nif (!ok) {\n    throw new IllegalArgumentException(\"format codes must be 0 (text) or 1 (binary)\");\n}\nPostgreSQLValueFormat.valueOf(code); // now safe","typeGuard":"static boolean isValidPgFormatCode(final int code) {\n    return code == 0 || code == 1;\n}","tryCatchPattern":"try {\n    PostgreSQLValueFormat.valueOf(code);\n} catch (UnsupportedSQLOperationException ex) {\n    // invalid wire data: terminate the connection; format codes outside 0/1 cannot be recovered mid-message\n    connection.closeDueToProtocolError(ex);\n}","preventionTips":["Use established drivers instead of hand-rolled Bind messages","Unit-test custom protocol writers to assert every format code emitted is 0 or 1"],"tags":["postgresql","protocol","format-code","extended-protocol","validation"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}