brettwooldridge/HikariCP · error · SQLException

Wrapped DatabaseMetaData is not an instance of {}

Error message

Wrapped DatabaseMetaData is not an instance of {}

What it means

ProxyDatabaseMetaData.unwrap(iface) throws SQLException unless the delegated DatabaseMetaData implements the requested interface or can unwrap it. HikariCP proxies metadata objects obtained from pooled connections, so unwrap only reaches the driver's real metadata object.

Source

Thrown at src/main/java/com/zaxxer/hikari/pool/ProxyDatabaseMetaData.java:346

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

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Call metaData.isWrapperFor(iface) first
2. Unwrap to the driver's documented metadata interface, or query standard DatabaseMetaData methods instead
3. If it fails for vendor extras, unwrap the Connection first and call getMetaData on the vendor connection

Example fix

// before
var vmd = conn.getMetaData().unwrap(VendorMetaData.class);

// after
var md = conn.getMetaData();
if (md.isWrapperFor(VendorMetaData.class)) {
   var vmd = md.unwrap(VendorMetaData.class);
}

if (conn.getMetaData().isWrapperFor(VendorMetaData.class)) { ... }

boolean canUnwrapMd(DatabaseMetaData md, Class<?> iface) {
    try { return md.isWrapperFor(iface); }
    catch (SQLException e) { return false; }
}

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

When it happens

Trigger: metaData.unwrap(SomeVendorMetaData.class) where the driver does not expose such a type; unwrapping metadata of a connection whose driver is generic (jdbc:Url based DriverDataSource) and provides no vendor metadata interface.

Common situations: Vendor feature detection via metadata unwrapping, tests with mocked DatabaseMetaData, drivers whose metadata only unwrap to standard interfaces.

Related errors

• Wrapped DataSource is not an instance of ${iface}
• Wrapped connection is not an instance of ${iface}
• Wrapped ResultSet 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/965129cff18bae30. Report an issue: GitHub.