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

PostgreSQLTextArrayValueParser.parse constructs a PGobject typed 'text[]'; a SQLException during setValue is wrapped in SQLWrapperException with the 'Underlying SQL state / error code' message. It triggers when a text bind parameter for a text[] column is not a valid PostgreSQL array literal.

Source

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

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

import java.sql.SQLException;

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

View on GitHub (pinned to e952770a21)

Solutions

  1. Build array literals with a helper (e.g. org.postgresql.jdbc PgArray or PreparedStatement.createArrayOf) instead of string concatenation
  2. Wrap the value in braces and quote elements containing commas/braces: "{a,b}"
  3. Validate the literal against PostgreSQL array syntax before binding
  4. Inspect the wrapped SQLException for the exact parse position

Example fix

// before
stmt.setString(1, "red,green");
// after
stmt.setArray(1, conn.createArrayOf("text", new String[]{"red","green"}));
Defensive patterns

Strategy: validation

Validate before calling

boolean validPgArray(String s) { return s != null && s.startsWith("{") && s.endsWith("}") && balancedQuotes(s); }

Try / catch

catch (SQLWrapperException e) { /* log cause SQLState; tell caller the array literal is malformed */ }

Prevention

When it happens

Trigger: Binding values like '{a,b' (unclosed brace), 'a,b,c' (missing array braces), nested-quote mistakes like '{"x}', or stray backslashes during extended-protocol bind for a text[] parameter.

Common situations: Applications building array literals by hand with string concatenation, forgetting the {..} wrapper, or mishandling embedded commas/quotes in elements.

Related errors

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