apache/shardingsphere · error · FirebirdProtocolException

Missing required format info in createBatch()

Error message

Missing required format info in createBatch()

What it means

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.

Source

Thrown at database/protocol/dialect/firebird/src/main/java/org/apache/shardingsphere/database/protocol/firebird/packet/command/query/batch/FirebirdBatchCreateCommandPacket.java:45

 * Firebird create batch command packet.
 */
@Getter
public final class FirebirdBatchCreateCommandPacket extends FirebirdCommandPacket {
    
    private final int statementHandle;
    
    private final ByteBuf batchBlr;
    
    private final long batchMessageLength;
    
    private final ByteBuf batchParametersBuffer;
    
    public FirebirdBatchCreateCommandPacket(final FirebirdPacketPayload payload) {
        payload.skipReserved(4);
        statementHandle = payload.readInt4();
        batchBlr = payload.readBuffer();
        if (!batchBlr.isReadable()) {
            throw new FirebirdProtocolException("Missing required format info in createBatch()");
        }
        batchMessageLength = payload.readInt4Unsigned();
        batchParametersBuffer = payload.readBuffer();
    }
    
    @Override
    protected void write(final FirebirdPacketPayload payload) {
    }
    
    /**
     * Get length of packet.
     *
     * @param payload Firebird packet payload
     * @return length of packet
     */
    public static int getLength(final FirebirdPacketPayload payload) {
        int length = 8;
        length += payload.getBufferLength(length);

View on GitHub (pinned to e952770a21)

Solutions

1. 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.
2. Remove driver-level charset overrides (charSet=, encoding=, ANCII/latin1 DSN entries) that force a non-UTF8 value.
3. Convert non-UTF8 data to UTF-8 before sending it through the proxy; the proxy will not transcode.
4. If you truly need another encoding, connect to the backend database directly — the proxy frontend supports UTF-8 only.

Example fix

# before
PGOPTIONS='-c client_encoding=latin1' psql -h proxy -p 3307

# after
PGOPTIONS='-c client_encoding=UTF8' psql -h proxy -p 3307

// Client-side: normalize and whitelist client_encoding before connecting
String enc = normalize(clientEncoding); // strip quotes, lowercase
if (!(enc.equals("default") || Set.of("utf8", "utf-8", "utf_8", "unicode").contains(enc))) {
    clientEncoding = "UTF8"; // or fail fast
}

// Surfaced as a PostgreSQL-style error during connection/startup; not retryable
try {
    conn = DriverManager.getConnection(pgUrl, props);
} catch (PSQLException e) {
    if (e.getMessage().contains("client_encoding")) {
        props.setProperty("options", "-c client_encoding=UTF8");
        conn = DriverManager.getConnection(pgUrl, props); // retry once with UTF8
    } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• isc_charset_not_found
• Can not support type `%s`.
• Invalid batch handle: statement handle %d
• Connection [%s] is not registered.
• BLR is too short: %s

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