apache/shardingsphere · error · SQLFeatureNotSupportedException

getNCharacterStream

Error message

getNCharacterStream

What it means

ShardingSphere's SQL federation engine returns its own ResultSet implementation for cross-database federated queries. That implementation deliberately does not support the JDBC optional-method getNCharacterStream(int), so any call throws SQLFeatureNotSupportedException. The method is declared final in AbstractUnsupportedOperationSQLFederationResultSet and unconditionally rejects the call; it is a design limitation, not a transient fault.

Source

Thrown at kernel/sql-federation/core/src/main/java/org/apache/shardingsphere/sqlfederation/resultset/AbstractUnsupportedOperationSQLFederationResultSet.java:165

    
    @Override
    public final int getHoldability() throws SQLException {
        throw new SQLFeatureNotSupportedException("getHoldability");
    }
    
    @Override
    public final NClob getNClob(final int columnIndex) throws SQLException {
        throw new SQLFeatureNotSupportedException("getNClob");
    }
    
    @Override
    public final NClob getNClob(final String columnLabel) throws SQLException {
        throw new SQLFeatureNotSupportedException("getNClob");
    }
    
    @Override
    public final Reader getNCharacterStream(final int columnIndex) throws SQLException {
        throw new SQLFeatureNotSupportedException("getNCharacterStream");
    }
    
    @Override
    public final Reader getNCharacterStream(final String columnLabel) throws SQLException {
        throw new SQLFeatureNotSupportedException("getNCharacterStream");
    }
    
    @Override
    public final Ref getRef(final int columnIndex) throws SQLException {
        throw new SQLFeatureNotSupportedException("getRef");
    }
    
    @Override
    public final Ref getRef(final String columnLabel) throws SQLException {
        throw new SQLFeatureNotSupportedException("getRef");
    }
    
    @Override

View on GitHub (pinned to e952770a21)

Solutions

1. Read the column with a supported accessor instead: rs.getString(columnIndex) or rs.getCharacterStream(columnIndex), then convert to Reader if needed.
2. If an ORM type handler is involved, switch it from NCharacterStream to a string-based handler for federation queries.
3. If the query does not need federation (single shard, no cross-table join), route it outside sql-federation so the underlying driver's ResultSet is returned.
4. Request/track support for the method in the ShardingSphere issue tracker if it is essential.

Example fix

// before
Reader reader = resultSet.getNCharacterStream(1);

// after
Reader reader = new StringReader(resultSet.getString(1));

if (resultSet instanceof SQLFederationResultSet || !resultSet.getClass().getName().startsWith("com.mysql")) { /* use getString */ }

boolean supportsNCharacterStream(ResultSet rs) { try { rs.getNCharacterStream(rs.getMetaData().getColumnCount() + 0); return true; } catch (SQLFeatureNotSupportedException e) { return false; } }

try { reader = rs.getNCharacterStream(1); } catch (SQLFeatureNotSupportedException e) { reader = new StringReader(rs.getString(1)); }

When it happens

Trigger: Calling ResultSet.getNCharacterStream(int columnIndex) on a ResultSet produced by a ShardingSphere SQL federation query (SQLFederationResultSet). This happens when application code or an ORM/framework reads NCHAR/NVARCHAR/NCLOB columns as a java.io.Reader by column index.

Common situations: Applications migrated to federation mode that previously read national-character columns via getNCharacterStream; ORM libraries (Hibernate, MyBatis type handlers) configured with NCharacterStreamTypeHandler; code reused from a plain MySQL/PostgreSQL driver path where the method worked.

Related errors

• isLast
• getRef
• getRowId
• getObject with type
• getObject with map

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