{"record":{"id":"965129cff18bae30","repo":"brettwooldridge/HikariCP","slug":"wrapped-databasemetadata-is-not-an-instance-of","errorCode":null,"errorMessage":"Wrapped DatabaseMetaData is not an instance of {}","messagePattern":"Wrapped DatabaseMetaData is not an instance of (.+?)","errorType":"exception","errorClass":"SQLException","httpStatus":null,"severity":"error","filePath":"src/main/java/com/zaxxer/hikari/pool/ProxyDatabaseMetaData.java","lineNumber":346,"sourceCode":"   @Override\n   public final boolean isWrapperFor(Class<?> iface) throws SQLException\n   {\n      return iface.isInstance(delegate) || (delegate != null && delegate.isWrapperFor(iface));\n   }\n\n   /** {@inheritDoc} */\n   @Override\n   @SuppressWarnings(\"unchecked\")\n   public final <T> T unwrap(Class<T> iface) throws SQLException\n   {\n      if (iface.isInstance(delegate)) {\n         return (T) delegate;\n      }\n      else if (delegate != null) {\n         return delegate.unwrap(iface);\n      }\n\n      throw new SQLException(\"Wrapped DatabaseMetaData is not an instance of \" + iface);\n   }\n}\n","sourceCodeStart":328,"sourceCodeEnd":349,"githubUrl":"https://github.com/brettwooldridge/HikariCP/blob/a4d93f4f85517f90e632b795486d7102e933d7ff/src/main/java/com/zaxxer/hikari/pool/ProxyDatabaseMetaData.java#L328-L349","documentation":"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.","triggerScenarios":"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.","commonSituations":"Vendor feature detection via metadata unwrapping, tests with mocked DatabaseMetaData, drivers whose metadata only unwrap to standard interfaces.","solutions":["Call metaData.isWrapperFor(iface) first","Unwrap to the driver's documented metadata interface, or query standard DatabaseMetaData methods instead","If it fails for vendor extras, unwrap the Connection first and call getMetaData on the vendor connection"],"exampleFix":"// before\nvar vmd = conn.getMetaData().unwrap(VendorMetaData.class);\n\n// after\nvar md = conn.getMetaData();\nif (md.isWrapperFor(VendorMetaData.class)) {\n   var vmd = md.unwrap(VendorMetaData.class);\n}","handlingStrategy":"type-guard","validationCode":"if (conn.getMetaData().isWrapperFor(VendorMetaData.class)) { ... }","typeGuard":"boolean canUnwrapMd(DatabaseMetaData md, Class<?> iface) {\n    try { return md.isWrapperFor(iface); }\n    catch (SQLException e) { return false; }\n}","tryCatchPattern":"try { v = md.unwrap(iface); }\ncatch (SQLException e) {\n    if (e.getMessage().contains(\"not an instance of\")) { /* use standard metadata calls */ }\n    else throw e;\n}","preventionTips":["Prefer standard DatabaseMetaData methods","Guard unwrap with isWrapperFor","Unwrap the connection instead when vendor metadata is needed"],"tags":["hikaricp","jdbc","unwrap","metadata"],"backgroundTag":null,"analyzedSha":"a4d93f4f85517f90e632b795486d7102e933d7ff","analyzedAt":"2026-08-14T12:11:37.292Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}