{"record":{"id":"b58917432fb71f35","repo":"jd-opensource/joyagent-jdgenie","slug":"could-not-find-any-jdbc-dialect-factories-that-imp","errorCode":null,"errorMessage":"Could not find any jdbc dialect factories that implement '%s' in the classpath.","messagePattern":"Could not find any jdbc dialect factories that implement '(.+?)' in the classpath\\.","errorType":"exception","errorClass":"JdbcBizException","httpStatus":null,"severity":"error","filePath":"genie-backend/src/main/java/com/jd/genie/data/jdbc/catalog/JdbcCatalogLoader.java","lineNumber":24,"sourceCode":"import lombok.extern.slf4j.Slf4j;\n\nimport java.util.LinkedList;\nimport java.util.List;\nimport java.util.ServiceConfigurationError;\nimport java.util.ServiceLoader;\n\n@Slf4j\npublic final class JdbcCatalogLoader {\n    private JdbcCatalogLoader() {\n    }\n\n\n    public static JdbcCatalog load(DialectEnum jdbcDialect) {\n        ClassLoader cl = Thread.currentThread().getContextClassLoader();\n        List<JdbcCatalogFactory> foundFactories = discoverFactories(cl);\n\n        if (foundFactories.isEmpty()) {\n            throw new JdbcBizException(String.format(\n                    \"Could not find any jdbc dialect factories that implement '%s' in the classpath.\",\n                    JdbcCatalog.class.getName()));\n        }\n\n        final List<JdbcCatalogFactory> matchingFactories =\n                foundFactories.stream().filter(f -> f.jdbcDialect() == jdbcDialect).toList();\n        if (matchingFactories.isEmpty()) {\n            throw new CatalogException(\"Could not find any jdbc dialect factory that can handled \");\n        }\n        if (matchingFactories.size() > 1) {\n            throw new JdbcBizException(\"Multiple jdbc dialect factories can handle\");\n        }\n\n        return matchingFactories.get(0).createCatalog();\n    }\n\n\n    private static List<JdbcCatalogFactory> discoverFactories(ClassLoader classLoader) {","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/jd-opensource/joyagent-jdgenie/blob/2417e0b8b636d941ad5fb14c59b20dddfef5375d/genie-backend/src/main/java/com/jd/genie/data/jdbc/catalog/JdbcCatalogLoader.java#L6-L42","documentation":"JdbcCatalogLoader.load discovers JdbcCatalogFactory implementations via ServiceLoader (META-INF/services). If none are found on the classpath at all, it throws JdbcBizException stating no jdbc dialect factories implementing JdbcCatalogFactory exist. This is a SPI/dependency packaging failure, not a dialect mismatch.","triggerScenarios":"load(dialect) invoked with a classloader that cannot see any JdbcCatalogFactory service registration — the jdbc-catalog module or a specific dialect provider jar is absent from the runtime classpath.","commonSituations":"Maven/Gradle dependency for the dialect module not declared or marked provided; fat-jar build excluded META-INF/services entries (missing SPI merging); shaded jar stripping service files; running with a classloader that doesn't see the provider jar.","solutions":["Add the jdbc catalog/dialect provider dependency (e.g., genie-data-jdbc-<dialect>) to the runtime classpath.","Verify META-INF/services/<JdbcCatalogFactory FQCN> files exist inside the packaged jar.","If shading, configure the shade plugin to merge service descriptor files (ServicesResourceTransformer).","Confirm Thread.currentThread().getContextClassLoader() can load the provider (check container/app-server classloading)."],"exampleFix":"// before (pom.xml)\n<!-- dialect provider jar missing -->\n// after (pom.xml)\n<dependency>\n  <groupId>com.jd.genie</groupId>\n  <artifactId>genie-data-jdbc-mysql</artifactId>\n  <version>...</version>\n</dependency>","handlingStrategy":"validation","validationCode":"// check SPI registration before calling load\nClassLoader cl = Thread.currentThread().getContextClassLoader();\nEnumeration<URL> res = cl.getResources(\"META-INF/services/com.jd.genie.data.jdbc.catalog.JdbcCatalogFactory\");\nif (!res.hasMoreElements()) {\n    throw new IllegalStateException(\"JdbcCatalogFactory SPI file missing from classpath\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    JdbcCatalog catalog = JdbcCatalogLoader.load(dialect);\n} catch (JdbcBizException e) {\n    if (e.getMessage().contains(\"Could not find any jdbc dialect factories\")) {\n        // add provider jar / fix packaging, then retry\n    } else throw e;\n}","preventionTips":["Declare every dialect provider jar as a runtime dependency.","Verify META-INF/services files survive packaging (unzip -l the jar).","When shading, merge service descriptors with ServicesResourceTransformer.","Smoke-test catalog loading at app startup, not on first use."],"tags":["java","spi","classpath","jdbc","service-loader"],"backgroundTag":"missing-dependency","analyzedSha":"2417e0b8b636d941ad5fb14c59b20dddfef5375d","analyzedAt":"2026-09-08T11:28:19.414Z","contentChangedAt":"2026-09-08T11:28:19.414Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}