{"record":{"id":"7b2d31242f74ef26","repo":"apache/shardingsphere","slug":"underlying-sql-state-s-underlying-error-code","errorCode":null,"errorMessage":"Underlying SQL state: %s, underlying error code: %s.","messagePattern":"Underlying SQL state: (.+?), underlying error code: (.+?)\\.","errorType":"exception","errorClass":"SQLWrapperException","httpStatus":null,"severity":"error","filePath":"database/protocol/dialect/postgresql/src/main/java/org/apache/shardingsphere/database/protocol/postgresql/packet/command/query/extended/bind/protocol/text/impl/PostgreSQLBitValueParser.java","lineNumber":39,"sourceCode":"import org.apache.shardingsphere.infra.exception.external.sql.type.wrapper.SQLWrapperException;\nimport org.postgresql.util.PGobject;\n\nimport java.sql.SQLException;\n\n/**\n * Bit value parser of PostgreSQL.\n */\npublic final class PostgreSQLBitValueParser implements PostgreSQLTextValueParser<PGobject> {\n    \n    @Override\n    public PGobject parse(final String value) {\n        try {\n            PGobject result = new PGobject();\n            result.setType(\"bit\");\n            result.setValue(value);\n            return result;\n        } catch (final SQLException ex) {\n            throw new SQLWrapperException(ex);\n        }\n    }\n}\n","sourceCodeStart":21,"sourceCodeEnd":43,"githubUrl":"https://github.com/apache/shardingsphere/blob/e952770a215630a3659c75d64369168cd3e26b82/database/protocol/dialect/postgresql/src/main/java/org/apache/shardingsphere/database/protocol/postgresql/packet/command/query/extended/bind/protocol/text/impl/PostgreSQLBitValueParser.java#L21-L43","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Validate the bind value is a pure 0/1 string of the exact width of the bit(n) column before binding","Bind the parameter as typed binary or let the driver convert, instead of sending an arbitrary string","Inspect the cause of the SQLWrapperException (SQLException state/code) to identify the exact validation failure","Correct or normalize the value at the application layer (strip non-binary characters, fix length)"],"exampleFix":"// before\nstmt.setString(1, \"21\"); // invalid bit literal\n// after\nstmt.setString(1, \"10\"); // matches bit(2)","handlingStrategy":"validation","validationCode":"boolean validBit(String s, int width) { return s != null && s.matches(\"[01]{\" + width + \"}\"); }","typeGuard":null,"tryCatchPattern":"catch (SQLWrapperException e) { logSQLException(e.getCause()); /* surface state/code from cause */ }","preventionTips":["Validate bit literals client-side (only 0/1, exact width)","Bind typed values instead of raw strings where possible","Log the wrapped SQLException state and code to classify parse failures"],"tags":["postgresql","bind","bit-type","value-parsing"],"backgroundTag":null,"analyzedSha":"e952770a215630a3659c75d64369168cd3e26b82","analyzedAt":"2026-08-14T13:54:53.392Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}