{"record":{"id":"00af6db234ef6ec1","repo":"jd-opensource/joyagent-jdgenie","slug":"could-not-load-service-provider-for-catalog-factor","errorCode":null,"errorMessage":"Could not load service provider for Catalog factory.","messagePattern":"Could not load service provider for Catalog factory\\.","errorType":"exception","errorClass":"JdbcBizException","httpStatus":null,"severity":"error","filePath":"genie-backend/src/main/java/com/jd/genie/data/jdbc/catalog/JdbcCatalogLoader.java","lineNumber":51,"sourceCode":"        }\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) {\n        try {\n            final List<JdbcCatalogFactory> result = new LinkedList<>();\n            ServiceLoader.load(JdbcCatalogFactory.class, classLoader)\n                    .iterator()\n                    .forEachRemaining(result::add);\n            return result;\n        } catch (ServiceConfigurationError e) {\n            log.error(\"Could not load service provider for Catalog factory.\", e);\n            throw new JdbcBizException(\n                    \"Could not load service provider for Catalog factory.\", e);\n        }\n    }\n}\n","sourceCodeStart":33,"sourceCodeEnd":56,"githubUrl":"https://github.com/jd-opensource/joyagent-jdgenie/blob/2417e0b8b636d941ad5fb14c59b20dddfef5375d/genie-backend/src/main/java/com/jd/genie/data/jdbc/catalog/JdbcCatalogLoader.java#L33-L56","documentation":"discoverFactories iterates ServiceLoader.load(JdbcCatalogFactory.class, classLoader); if the SPI machinery itself fails (ServiceConfigurationError — e.g., a provider class listed in META-INF/services cannot be instantiated), it logs and rethrows as JdbcBizException('Could not load service provider for Catalog factory.'). Unlike error 16, providers ARE registered but broken/unloadable.","triggerScenarios":"A META-INF/services entry names a class that is missing, fails static initialization, or whose constructor throws — ServiceLoader iteration raises ServiceConfigurationError, caught and wrapped by discoverFactories.","commonSituations":"Partial deployments where the service file exists but the implementation class was relocated/renamed in a refactor; provider class depends on an optional dependency not on the classpath (NoClassDefFoundError during init); shaded jars mangling provider class names.","solutions":["Inspect the wrapped ServiceConfigurationError cause — it names the failing provider class and reason.","Fix the META-INF/services entry to match the provider class's actual fully-qualified name.","Add the missing dependency the provider needs at initialization time.","Rebuild/redeploy the jar so service files and implementation classes are consistent."],"exampleFix":"// before (META-INF/services/com.jd.genie.data.jdbc.catalog.JdbcCatalogFactory)\ncom.jd.genie.data.jdbc.catalog.MySqlCatalogFactory  // class renamed in refactor\n// after\ncom.jd.genie.data.jdbc.catalog.mysql.MySqlJdbcCatalogFactory","handlingStrategy":"try-catch","validationCode":"// verify provider class is loadable before iteration\nfor (String cls : readServiceProviderLines(cl)) {\n    try { Class.forName(cls, false, cl); }\n    catch (Throwable t) { throw new IllegalStateException(\"Unloadable SPI provider: \" + cls, t); }\n}","typeGuard":null,"tryCatchPattern":"try {\n    JdbcCatalog catalog = JdbcCatalogLoader.load(dialect);\n} catch (JdbcBizException e) {\n    if (e.getMessage().contains(\"Could not load service provider\")) {\n        // inspect e.getCause() (ServiceConfigurationError) for the broken provider class\n    } else throw e;\n}","preventionTips":["Keep META-INF/services entries in sync with refactored class names.","Declare all classes the provider needs at init as hard dependencies.","Exercise ServiceLoader discovery in a startup health check.","Beware shading: unmangle/verify provider class names post-relocation."],"tags":["java","spi","service-loader","class-not-found","jdbc"],"backgroundTag":"class-not-found","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"}