apache/shardingsphere · error · UnsupportedSQLOperationException
setClientInfo properties
Error message
setClientInfo properties
What it means
ShardingSphere's JDBC driver does not implement the java.sql.Connection method setClientInfo properties (bulk-setting JDBC 4 client info properties on the connection). The abstract base class AbstractUnsupportedOperationConnection, which ShardingSphereConnection extends, overrides it as final and unconditionally throws SQLFeatureNotSupportedException. ShardingSphere deliberately rejects client-info mutation with UnsupportedSQLOperationException, so the Properties-based setter always throws. The exception is thrown the moment the method is invoked on any connection produced by the ShardingSphere Driver.
Source
Thrown at jdbc/src/main/java/org/apache/shardingsphere/driver/jdbc/unsupported/AbstractUnsupportedOperationConnection.java:134
@Override
public final Properties getClientInfo() throws SQLException {
throw new SQLFeatureNotSupportedException("getClientInfo");
}
@Override
public final String getClientInfo(final String name) throws SQLException {
throw new SQLFeatureNotSupportedException("getClientInfo name");
}
@Override
public final void setClientInfo(final String name, final String value) {
throw new UnsupportedSQLOperationException("setClientInfo name value");
}
@Override
public final void setClientInfo(final Properties props) {
throw new UnsupportedSQLOperationException("setClientInfo properties");
}
}
View on GitHub (pinned to e952770a21)
Solutions
- Drop the bulk setClientInfo call for ShardingSphere connections, or guard it with a catch of SQLFeatureNotSupportedException.
- Encode the equivalent settings in each storage unit's JDBC URL inside the ShardingSphere configuration.
- Iterate unwrap(connection) per backend and apply properties there if backend-level state is required.
Defensive patterns
Strategy: try-catch
Validate before calling
boolean supportsOp = false;
try {
connection.getMetaData(); // connection is alive
// JDBC has no capability flag for individual methods; probe once per JVM:
supportsOp = probeSupport(connection); // reflective/one-time guarded call
} catch (final SQLException ignored) {
}
// Simpler and recommended: capability-check by driver URL
boolean isShardingSphere = url.startsWith("jdbc:shardingsphere:");
if (isShardingSphere) {
// skip the unsupported call, use the alternative API path
} Try / catch
try {
connection.setClientInfo(/* args */);
} catch (final SQLFeatureNotSupportedException e) {
// expected on ShardingSphere connections: fall back to supported API
log.debug("Driver does not support setClientInfo properties, using fallback", e);
} Prevention
- Bulk client-info application at pool checkout must be guarded by a driver check; encode equivalent properties in storage-unit JDBC URLs instead.
- Check the JDBC URL before calling optional JDBC 4 methods: connections starting with jdbc:shardingsphere: never support the lob/network-timeout/client-info/callable APIs.
- Catch java.sql.SQLFeatureNotSupportedException (parent of ShardingSphere's UnsupportedSQLOperationException) around optional driver-capability calls so the application degrades gracefully.
When it happens
Trigger: Calling Connection.setClientInfo(properties) with a non-empty Properties object on a ShardingSphere connection.
Common situations: Framework/pool startup code that copies client info onto every new connection; monitoring agents applying a property bundle after checkout; migrations from drivers that accept these properties.
Related errors
AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14).
Data as JSON: /api/errors/89f0fd16010b4cd5.
Report an issue: GitHub.