brettwooldridge/HikariCP · error · SQLException

Wrapped ResultSet is not an instance of {}

Error message

Wrapped ResultSet is not an instance of {}

What it means

ProxyResultSet.unwrap(iface) throws SQLException when the underlying driver ResultSet does not implement the requested interface and cannot unwrap to it. ResultSets handed out by HikariCP proxies are thin wrappers; unwrap success depends entirely on the delegate's capabilities.

Source

Thrown at src/main/java/com/zaxxer/hikari/pool/ProxyResultSet.java:108

   @Override
   public final boolean isWrapperFor(Class<?> iface) throws SQLException
   {
      return iface.isInstance(delegate) || (delegate != null && delegate.isWrapperFor(iface));
   }

   /** {@inheritDoc} */
   @Override
   @SuppressWarnings("unchecked")
   public final <T> T unwrap(Class<T> iface) throws SQLException
   {
      if (iface.isInstance(delegate)) {
         return (T) delegate;
      }
      else if (delegate != null) {
          return delegate.unwrap(iface);
      }

      throw new SQLException("Wrapped ResultSet is not an instance of " + iface);
   }
}

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Check rs.isWrapperFor(iface) before calling unwrap
2. Prefer standard JDBC APIs (getObject, getArray) over vendor-specific unwrap paths
3. Cast the vendor object at fetch time (driver returns vendor types from getObject) rather than unwrapping the ResultSet

Example fix

// before
OracleResultSet ors = rs.unwrap(OracleResultSet.class);

// after
java.sql.Array arr = rs.getArray(1); // standard API
// or guard:
if (rs.isWrapperFor(OracleResultSet.class)) { ... }

if (rs.isWrapperFor(VendorResultSet.class)) { ... }

boolean canUnwrapRs(ResultSet rs, Class<?> iface) {
    try { return !rs.isClosed() && rs.isWrapperFor(iface); }
    catch (SQLException e) { return false; }
}

try { v = rs.unwrap(iface); }
catch (SQLException e) {
    if (e.getMessage().contains("not an instance of")) { /* use getObject/getArray standard APIs */ }
    else throw e;
}

When it happens

Trigger: rs.unwrap(VendorResultSet.class) for vendor cursor/array APIs the driver does not expose on ResultSet; using unwrap on closed result sets whose delegate is ClosedConnection-like; wrong interface passed (e.g. a Statement type).

Common situations: Vendor streaming/cursor APIs, Oracle ARRAY/STRUCT fetch helpers, tests with fake ResultSets.

Related errors

• Wrapped DataSource is not an instance of ${iface}
• Wrapped connection is not an instance of ${iface}
• Wrapped DatabaseMetaData is not an instance of {}
• Wrapped statement is not an instance of {}
• DataSource returned null unexpectedly

AI-assisted analysis of brettwooldridge/HikariCP@a4d93f4f85 (2026-08-14). Data as JSON: /api/errors/17aee1810e8e5e7f. Report an issue: GitHub.