{"record":{"id":"efe4073173ce9779","repo":"hibernate/hibernate-orm","slug":"could-not-instantiate-specified-dialect-class-di","errorCode":null,"errorMessage":"Could not instantiate specified Dialect class [<dialectClassName>]","messagePattern":"Could not instantiate specified Dialect class \\[<dialectClassName>\\]","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"critical","filePath":"hibernate-core/src/main/java/org/hibernate/engine/jdbc/dialect/spi/BasicDialectResolver.java","lineNumber":80,"sourceCode":"\n\t@Override\n\tpublic final Dialect resolveDialect(DialectResolutionInfo info) {\n\t\tfinal String databaseName = info.getDatabaseName();\n\t\tfinal int databaseMajorVersion = info.getDatabaseMajorVersion();\n\t\tfinal int databaseMinorVersion = info.getDatabaseMinorVersion();\n\n\t\tif ( nameToMatch.equalsIgnoreCase( databaseName )\n\t\t\t\t&& ( majorVersionToMatch == NO_VERSION || majorVersionToMatch == databaseMajorVersion )\n\t\t\t\t&& ( minorVersionToMatch == NO_VERSION || minorVersionToMatch == databaseMinorVersion ) ) {\n\t\t\ttry {\n\t\t\t\treturn (Dialect) dialectClass.newInstance();\n\t\t\t}\n\t\t\tcatch (HibernateException e) {\n\t\t\t\t// conceivable that the dialect ctor could throw HibernateExceptions, so don't re-wrap\n\t\t\t\tthrow e;\n\t\t\t}\n\t\t\tcatch (Throwable t) {\n\t\t\t\tthrow new HibernateException(\n\t\t\t\t\t\t\"Could not instantiate specified Dialect class [\" + dialectClass.getName() + \"]\",\n\t\t\t\t\t\tt\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\treturn null;\n\t}\n}\n","sourceCodeStart":62,"sourceCodeEnd":90,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/engine/jdbc/dialect/spi/BasicDialectResolver.java#L62-L90","documentation":"BasicDialectResolver (built from @Database/version metadata plus a dialect class) matched the current database name and version, then tried dialectClass.newInstance() to construct the dialect. Any Throwable other than a HibernateException from that reflective construction is wrapped as HibernateException('Could not instantiate specified Dialect class [...]') with the original throwable as cause; HibernateExceptions thrown by the constructor are rethrown unwrapped.","triggerScenarios":"A custom dialect annotated with @Database + @DialectResolution registers a dialect class that is abstract, has a non-public or missing no-arg constructor, or whose constructor throws ( linkage errors, illegal state) when the database name/version matches.","commonSituations":"Community/custom dialects whose class requires constructor arguments; dialect classes made package-private; constructors that validate state and throw on unexpected environments; partially upgraded dialect jars missing a transitive class.","solutions":["Give the dialect class a public no-arg constructor and make the class concrete and public","Read the nested cause to see whether construction failed for access, abstractness, or an internal error","Ensure all classes the dialect constructor touches are on the classpath","If the constructor throws a HibernateException deliberately, fix that underlying condition instead"],"exampleFix":"// before\n@Database(name = \"MyDB\")\npublic class MyDbDialect extends Dialect {\n    MyDbDialect(DatabaseVersion v) { super(v); } // package-private, not no-arg\n}\n\n// after\n@Database(name = \"MyDB\")\npublic class MyDbDialect extends Dialect {\n    public MyDbDialect() { super(DatabaseVersion.make(16, 0)); }\n}","handlingStrategy":"validation","validationCode":"// for custom @Database-annotated dialects, verify instantiability in a unit test\nClass<?> c = MyDbDialect.class;\nassert !Modifier.isAbstract(c.getModifiers());\nassert Modifier.isPublic(c.getConstructor().getModifiers());\nDialect d = (Dialect) c.getConstructor().newInstance(); // fail at build time, not bootstrap","typeGuard":null,"tryCatchPattern":"try {\n    return resolver.resolveDialect(info);\n} catch (HibernateException e) {\n    Throwable root = e.getCause() != null ? e.getCause() : e;\n    log.error(\"Custom dialect class failed to instantiate: {}\", root, e);\n    throw e;\n}","preventionTips":["Give every custom dialect a public no-arg constructor and test its instantiation in CI","Avoid dialect constructors that validate environment state; move such checks to factory code"],"tags":["hibernate","dialect","reflection","custom-dialect","bootstrap"],"backgroundTag":"dialect-instantiation-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}