apache/shardingsphere · error · SQLWrapperException

Underlying SQL state: %s, underlying error code: %s.

Error message

Underlying SQL state: %s, underlying error code: %s.

What it means

PostgreSQLBitValueParser.parse wraps a java.sql.SQLException thrown while building a PGobject of type 'bit' in a SQLWrapperException. The message 'Underlying SQL state: %s, underlying error code: %s.' is the wrapper's format; the real cause is the PGobject failure. This parser runs when a text-format bind parameter declared as a bit column is converted for the extended protocol.

Source

Thrown at database/protocol/dialect/postgresql/src/main/java/org/apache/shardingsphere/database/protocol/postgresql/packet/command/query/extended/bind/protocol/text/impl/PostgreSQLBitValueParser.java:39

import org.apache.shardingsphere.infra.exception.external.sql.type.wrapper.SQLWrapperException;
import org.postgresql.util.PGobject;

import java.sql.SQLException;

/**
 * Bit value parser of PostgreSQL.
 */
public final class PostgreSQLBitValueParser implements PostgreSQLTextValueParser<PGobject> {
    
    @Override
    public PGobject parse(final String value) {
        try {
            PGobject result = new PGobject();
            result.setType("bit");
            result.setValue(value);
            return result;
        } catch (final SQLException ex) {
            throw new SQLWrapperException(ex);
        }
    }
}

View on GitHub (pinned to e952770a21)

Solutions

  1. Validate the bind value is a pure 0/1 string of the exact width of the bit(n) column before binding
  2. Bind the parameter as typed binary or let the driver convert, instead of sending an arbitrary string
  3. Inspect the cause of the SQLWrapperException (SQLException state/code) to identify the exact validation failure
  4. Correct or normalize the value at the application layer (strip non-binary characters, fix length)

Example fix

// before
stmt.setString(1, "21"); // invalid bit literal
// after
stmt.setString(1, "10"); // matches bit(2)
Defensive patterns

Strategy: validation

Validate before calling

boolean validBit(String s, int width) { return s != null && s.matches("[01]{" + width + "}"); }

Try / catch

catch (SQLWrapperException e) { logSQLException(e.getCause()); /* surface state/code from cause */ }

Prevention

When it happens

Trigger: Calling parse(value) via the extended-query bind path where the target column type is bit and the string value is not a valid bit literal (e.g. 'x12', empty string, wrong length for the declared bit width), causing PGobject.setValue to raise SQLException.

Common situations: Applications binding bit values through the proxy with malformed strings, width mismatches between the literal and the column definition, or driver/server version differences in bit literal validation.

Related errors

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