What causes "Underlying SQL state: %s, underlying error code: %s." in apache/shardingsphere?

Validate the payload parses as JSON before binding (use a JSON library on the client)

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

PostgreSQLJsonValueParser.parse builds a PGobject typed 'json'; any SQLException from PGobject.setValue is wrapped in SQLWrapperException ('Underlying SQL state / error code' message). It triggers when a text bind parameter for a json column fails PGobject's json validation.

Source

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

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

import java.sql.SQLException;

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

View on GitHub (pinned to e952770a21)

Solutions

Validate the payload parses as JSON before binding (use a JSON library on the client)
Use a JSON/JSONB-typed client type (e.g. PGobject with type json, or driver's Json support) instead of a raw string
Check the wrapped SQLException state/code for the precise validation failure
Guard against null/empty payloads with explicit NULL binding if the column allows it

Example fix

// before
stmt.setString(1, "{oops");
// after
new com.google.gson.JsonParser().parseString(jsonText); // throws early client-side
stmt.setString(1, jsonText);

Defensive patterns

Strategy: validation

Validate before calling

try { new org.json.JSONTokener(jsonText).nextValue(); return true; } catch (org.json.JSONException e) { return false; }

Try / catch

catch (SQLWrapperException e) { /* cause is SQLException from PGobject; surface to user as invalid JSON payload */ }

Prevention

Validate JSON with a real parser before binding
Never concatenate unvalidated user input into json parameters
Handle empty payloads explicitly (bind NULL if column allows)

When it happens

Trigger: Binding a parameter declared as json with a string that PGobject rejects, e.g. '{invalid json', truncated payloads, or a null/empty string passed where a json document is required, during extended-protocol bind.

Common situations: Payload truncation over the wire, encoding issues (invalid UTF-8 sequences), or applications inserting user-supplied strings without validating JSON first.

Related errors

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