brettwooldridge/HikariCP · error · SQLException

Wrapped statement is not an instance of {}

Error message

Wrapped statement is not an instance of {}

What it means

ProxyStatement.unwrap(iface) throws SQLException unless the delegate Statement implements the requested interface or can itself unwrap to it. HikariCP proxies statements created on pooled connections, delegating unwrap to the driver's real statement.

Source

Thrown at src/main/java/com/zaxxer/hikari/pool/ProxyStatement.java:256

   @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 statement is not an instance of " + iface);
   }
}

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Use stmt.isWrapperFor(iface) as a guard before unwrap
2. Unwrap to the exact vendor interface the driver documents (e.g. org.postgresql.PGStatement for getPrepareThreshold)
3. Set vendor hints via connection/statement properties or SQL hints instead where possible

Example fix

// before
((OraclePreparedStatement) stmt.unwrap(OraclePreparedStatement.class)).setRowPrefetch(100);

// after
if (stmt.isWrapperFor(oracle.jdbc.OraclePreparedStatement.class)) {
   stmt.unwrap(oracle.jdbc.OraclePreparedStatement.class).setRowPrefetch(100);
}

if (stmt.isWrapperFor(VendorStatement.class)) { ... }

boolean canUnwrapStmt(Statement s, Class<?> iface) {
    try { return !s.isClosed() && s.isWrapperFor(iface); }
    catch (SQLException e) { return false; }
}

try { v = stmt.unwrap(iface); }
catch (SQLException e) {
    if (e.getMessage().contains("not an instance of")) { /* set hints via properties instead */ }
    else throw e;
}

When it happens

Trigger: stmt.unwrap(OraclePreparedStatement.class)/PGStatement etc. when the underlying driver does not support it; unwrap with an interface unrelated to statements; prepared vs callable statement type mismatch.

Common situations: Setting vendor fetch/row prefetch hints, using vendor batching APIs, mocking statements in tests.

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 ResultSet is not an instance of {}
• DataSource returned null unexpectedly

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