apache/shardingsphere · error · UnsupportedSQLOperationException

setClientInfo name value

Error message

setClientInfo name value

What it means

ShardingSphere's JDBC driver does not implement the java.sql.Connection method setClientInfo name value (setting a single named JDBC 4 client info property (e.g. ApplicationName, ClientUser) 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 (an SQLFeatureNotSupportedException subtype without checked wrapping semantics), so the single-property 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:129

    
    @Override
    public final Struct createStruct(final String typeName, final Object[] attributes) throws SQLException {
        throw new SQLFeatureNotSupportedException("createStruct");
    }
    
    @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

1. Remove the setClientInfo call when running behind ShardingSphere, or wrap it in a tolerant catch.
2. Set the equivalent backend property in the storage-unit JDBC URL (e.g. PostgreSQL ApplicationName=..., MySQL connectionAttributes) so it reaches the real connections.
3. Unwrap the underlying driver connection and call setClientInfo on it directly, accepting per-backend rather than per-logical-connection semantics.

Example fix

// before
connection.setClientInfo("ApplicationName", "billing-service");

// after (set it on the backend URL instead)
// url: jdbc:postgresql://db-host:5432/app?ApplicationName=billing-service
// or unwrap the real connection:
try {
    connection.setClientInfo("ApplicationName", "billing-service");
} catch (final SQLException ignored) {
    // ShardingSphere driver does not support client info
}

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 {
    connection.setClientInfo(/* args */);
} catch (final SQLFeatureNotSupportedException e) {
    // expected on ShardingSphere connections: fall back to supported API
    log.debug("Driver does not support setClientInfo name value, using fallback", e);
}

When it happens

Trigger: Calling Connection.setClientInfo(name, value) on a ShardingSphere connection.

Common situations: APM agents (Datadog, Elastic, New Relic) stamping connection names at checkout; connection pools propagating end-user identity; SQL Server/PostgreSQL users setting ApplicationName for sys.dm_exec_sessions/pg_stat_activity visibility.

Related errors

• prepareCall
• nativeSQL
• abort
• getTypeMap
• setTypeMap

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