alibaba/spring-ai-alibaba · error · SQLFeatureNotSupportedException

unwrap is not supported

Error message

unwrap is not supported

What it means

SimpleJdbcDataSource implements the JDBC Wrapper interface but does not support unwrap(); any call throws SQLFeatureNotSupportedException with this message. The minimal DataSource wrapper exposes only basic connection acquisition.

Source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/store/stores/DatabaseStore.java:295

         * @return JDBC connection
         * @throws SQLException if connection opening fails
         */
        @Override
        public Connection getConnection(String username, String password) throws SQLException {
            return DriverManager.getConnection(jdbcUrl, username, password);
        }

        /**
         * Unwrap to vendor-specific interface.
         *
         * @param iface target interface
         * @return wrapped interface
         * @param <T> generic target type
         * @throws SQLException if unsupported
         */
        @Override
        public <T> T unwrap(Class<T> iface) throws SQLException {
            throw new SQLFeatureNotSupportedException("unwrap is not supported");
        }

        /**
         * Check if wrapper can provide target interface.
         *
         * @param iface target interface
         * @return false because unwrap is not supported
         * @param <T> generic target type
         * @throws SQLException never thrown in this implementation
         */
        @Override
        public boolean isWrapperFor(Class<?> iface) throws SQLException {
            return false;
        }

        /**
         * Return writer used for logging.
         *

View on GitHub (pinned to f82da0b50f)

Solutions

1. Pass a real javax.sql.DataSource (e.g. HikariDataSource) to DatabaseStore instead of relying on the built-in SimpleJdbcDataSource if your tooling requires unwrap
2. Remove/branch around unwrap() calls when using DatabaseStore's simple DataSource
3. Check instanceof / isWrapperFor before calling unwrap

Example fix

// before
Connection c = store.getDataSource().unwrap(org.postgresql.ds.PGPoolingDataSource.class).getConnection();
// after
try (Connection c = store.getDataSource().getConnection()) { /* use connection */ }

if (needsUnwrap) { throw new IllegalStateException("DatabaseStore's simple DataSource does not support unwrap; supply your own pooled DataSource"); }

try { T native = ds.unwrap(T.class); } catch (SQLException e) { log.warn("unwrap unsupported by DatabaseStore DataSource; use getConnection() instead"); }

When it happens

Trigger: Calling dataSource.unwrap(SomeInterface.class) or isWrapperFor-dependent tooling (connection pools, monitoring agents, ORM internals) on the DatabaseStore's internal DataSource.

Common situations: Framework instrumentation (e.g. Seata, Druid filters, Flyway internals) attempting to unwrap the native vendor DataSource; code written for pooled DataSource instances reused with this simple wrapper.

Related errors

• Unable to load checkpoints
• Unable to load latest checkpoint
• Unable to release checkpoint
• Unsupported dbType: {dbType}. Supported values: mysql, postg
• jdbcUrl cannot be null or blank

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/0b2e1e574e2eb823. Report an issue: GitHub.