{"record":{"id":"c11c741ad40754a2","repo":"apache/shardingsphere","slug":"missing-required-format-info-in-createbatch","errorCode":null,"errorMessage":"Missing required format info in createBatch()","messagePattern":"Missing required format info in createBatch\\(\\)","errorType":"exception","errorClass":"FirebirdProtocolException","httpStatus":null,"severity":"error","filePath":"database/protocol/dialect/firebird/src/main/java/org/apache/shardingsphere/database/protocol/firebird/packet/command/query/batch/FirebirdBatchCreateCommandPacket.java","lineNumber":45,"sourceCode":" * Firebird create batch command packet.\n */\n@Getter\npublic final class FirebirdBatchCreateCommandPacket extends FirebirdCommandPacket {\n    \n    private final int statementHandle;\n    \n    private final ByteBuf batchBlr;\n    \n    private final long batchMessageLength;\n    \n    private final ByteBuf batchParametersBuffer;\n    \n    public FirebirdBatchCreateCommandPacket(final FirebirdPacketPayload payload) {\n        payload.skipReserved(4);\n        statementHandle = payload.readInt4();\n        batchBlr = payload.readBuffer();\n        if (!batchBlr.isReadable()) {\n            throw new FirebirdProtocolException(\"Missing required format info in createBatch()\");\n        }\n        batchMessageLength = payload.readInt4Unsigned();\n        batchParametersBuffer = payload.readBuffer();\n    }\n    \n    @Override\n    protected void write(final FirebirdPacketPayload payload) {\n    }\n    \n    /**\n     * Get length of packet.\n     *\n     * @param payload Firebird packet payload\n     * @return length of packet\n     */\n    public static int getLength(final FirebirdPacketPayload payload) {\n        int length = 8;\n        length += payload.getBufferLength(length);","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/database/protocol/dialect/firebird/src/main/java/org/apache/shardingsphere/database/protocol/firebird/packet/command/query/batch/FirebirdBatchCreateCommandPacket.java#L27-L63","documentation":"Thrown by the PostgreSQL frontend when the client's startup parameter client_encoding (after normalization: lowercased, quotes stripped) is neither 'default' nor one of the accepted UTF-8 spellings ('utf8', 'utf-8', 'utf_8', 'unicode'). The proxy only supports UTF-8 conversations, so any other encoding is rejected with InvalidParameterValueException mirroring PostgreSQL's own 'invalid value for parameter' error.","triggerScenarios":"A PostgreSQL startup packet (or later parameter set) carrying client_encoding=latin1, win1252, euc-jp, sql_ascii, etc.; also quoted variants like \"'LATIN1'\" after formatClientEncoding normalization.","commonSituations":"Client tools with locale-derived default encodings (psql on Windows, JDBC with charSet/encoding set, older ODBC DSNs); migrations from setups where a non-UTF8 database was the norm; COPY or driver configuration explicitly pinning latin1/win1252.","solutions":["Set the client encoding to UTF8: JDBC url ?characterEncoding=UTF-8 / options=-c client_encoding=UTF8, psql: SET client_encoding TO 'UTF8'; PGCLIENTENCODING=UTF8 env var.","Remove driver-level charset overrides (charSet=, encoding=, ANCII/latin1 DSN entries) that force a non-UTF8 value.","Convert non-UTF8 data to UTF-8 before sending it through the proxy; the proxy will not transcode.","If you truly need another encoding, connect to the backend database directly — the proxy frontend supports UTF-8 only."],"exampleFix":"# before\nPGOPTIONS='-c client_encoding=latin1' psql -h proxy -p 3307\n\n# after\nPGOPTIONS='-c client_encoding=UTF8' psql -h proxy -p 3307","handlingStrategy":"validation","validationCode":"// Client-side: normalize and whitelist client_encoding before connecting\nString enc = normalize(clientEncoding); // strip quotes, lowercase\nif (!(enc.equals(\"default\") || Set.of(\"utf8\", \"utf-8\", \"utf_8\", \"unicode\").contains(enc))) {\n    clientEncoding = \"UTF8\"; // or fail fast\n}","typeGuard":null,"tryCatchPattern":"// Surfaced as a PostgreSQL-style error during connection/startup; not retryable\ntry {\n    conn = DriverManager.getConnection(pgUrl, props);\n} catch (PSQLException e) {\n    if (e.getMessage().contains(\"client_encoding\")) {\n        props.setProperty(\"options\", \"-c client_encoding=UTF8\");\n        conn = DriverManager.getConnection(pgUrl, props); // retry once with UTF8\n    } else { throw e; }\n}","preventionTips":["Standardize on PGCLIENTENCODING=UTF8 in deployment environments.","Remove charSet/encoding overrides from JDBC URLs and ODBC DSNs.","Ensure data is UTF-8 encoded before it reaches the proxy; no transcoding happens here."],"tags":["postgresql","encoding","authentication","startup","utf8"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}