jd-opensource/joyagent-jdgenie · error · JdbcBizException

Could not find any jdbc dialect factories that implement

Error message

Could not find any jdbc dialect factories that implement '%s' in the classpath.

What it means

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.

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).

Example fix

// before (pom.xml)
<!-- dialect provider jar missing -->
// after (pom.xml)
<dependency>
  <groupId>com.jd.genie</groupId>
  <artifactId>genie-data-jdbc-mysql</artifactId>
  <version>...</version>
</dependency>

Defensive patterns

Strategy: validation

Validate before calling

// check SPI registration before calling load
ClassLoader cl = Thread.currentThread().getContextClassLoader();
Enumeration<URL> res = cl.getResources("META-INF/services/com.jd.genie.data.jdbc.catalog.JdbcCatalogFactory");
if (!res.hasMoreElements()) {
    throw new IllegalStateException("JdbcCatalogFactory SPI file missing from classpath");
}

Try / catch

try {
    JdbcCatalog catalog = JdbcCatalogLoader.load(dialect);
} catch (JdbcBizException e) {
    if (e.getMessage().contains("Could not find any jdbc dialect factories")) {
        // add provider jar / fix packaging, then retry
    } else throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

AI-assisted analysis of jd-opensource/joyagent-jdgenie@2417e0b8b6 (2026-09-08). Data as JSON: /api/errors/b58917432fb71f35. Report an issue: GitHub.

Appendix: source

Thrown at genie-backend/src/main/java/com/jd/genie/data/jdbc/catalog/JdbcCatalogLoader.java:24

import lombok.extern.slf4j.Slf4j;

import java.util.LinkedList;
import java.util.List;
import java.util.ServiceConfigurationError;
import java.util.ServiceLoader;

@Slf4j
public final class JdbcCatalogLoader {
    private JdbcCatalogLoader() {
    }


    public static JdbcCatalog load(DialectEnum jdbcDialect) {
        ClassLoader cl = Thread.currentThread().getContextClassLoader();
        List<JdbcCatalogFactory> foundFactories = discoverFactories(cl);

        if (foundFactories.isEmpty()) {
            throw new JdbcBizException(String.format(
                    "Could not find any jdbc dialect factories that implement '%s' in the classpath.",
                    JdbcCatalog.class.getName()));
        }

        final List<JdbcCatalogFactory> matchingFactories =
                foundFactories.stream().filter(f -> f.jdbcDialect() == jdbcDialect).toList();
        if (matchingFactories.isEmpty()) {
            throw new CatalogException("Could not find any jdbc dialect factory that can handled ");
        }
        if (matchingFactories.size() > 1) {
            throw new JdbcBizException("Multiple jdbc dialect factories can handle");
        }

        return matchingFactories.get(0).createCatalog();
    }


    private static List<JdbcCatalogFactory> discoverFactories(ClassLoader classLoader) {

View on GitHub (pinned to 2417e0b8b6)