apache/seatunnel · warning

Failed to load JDBC driver {}

Error message

Failed to load JDBC driver {}

What it means

The Db2 CDC source factory attempts Class.forName on the Db2 JDBC driver (com.ibm.db2.jcc.DB2Driver) to register it with DriverManager before building the source. If the driver class cannot be loaded it logs this warning and continues; a later connection attempt will typically fail with 'No suitable driver' unless something else loads the driver.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-db2/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/db2/source/Db2IncrementalSourceFactory.java:113

                        StartupMode.INITIAL,
                        SourceOptions.EXACTLY_ONCE)
                .build();
    }

    @Override
    public Class<? extends SeaTunnelSource> getSourceClass() {
        return Db2IncrementalSource.class;
    }

    @Override
    public <T, SplitT extends SourceSplit, StateT extends Serializable>
            TableSource<T, SplitT, StateT> createSource(TableSourceFactoryContext context) {
        return () -> {
            // Load the JDBC driver in to DriverManager
            try {
                Class.forName(DRIVER_CLASS_NAME);
            } catch (Exception e) {
                log.warn("Failed to load JDBC driver {}", DRIVER_CLASS_NAME, e);
            }
            List<CatalogTable> catalogTables =
                    CatalogTableUtil.getCatalogTables(
                            context.getOptions(), context.getClassLoader());
            Optional<List<JdbcSourceTableConfig>> tableConfigs =
                    context.getOptions()
                            .getOptional(Db2IncrementalSourceOptions.TABLE_NAMES_CONFIG);
            if (tableConfigs.isPresent()) {
                catalogTables =
                        CatalogTableUtils.mergeCatalogTableConfig(
                                catalogTables,
                                tableConfigs.get(),
                                text -> TablePath.of(text, true));
            }
            return new Db2IncrementalSource(context.getOptions(), catalogTables);
        };
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Download the IBM Db2 JDBC driver (db2jcc / JCC) jar and place it in $SEATUNNEL_HOME/lib (or the connector plugin directory), then restart the cluster.
2. Add com.ibm.db2:jcc as a dependency in your own shaded distribution build if you assemble SeaTunnel yourself.
3. Verify the configured driver class name matches the jar you installed (com.ibm.db2.jcc.DB2Driver).
4. Confirm resolution by checking the warning's stack trace is gone and a test JDBC connection to Db2 succeeds with the same classpath.

Example fix

// before: driver jar missing -> warning at createSource, connect fails later
try {
    Class.forName(DRIVER_CLASS_NAME);
} catch (Exception e) {
    log.warn("Failed to load JDBC driver {}", DRIVER_CLASS_NAME, e);
}
// after: fail fast with an actionable message
try {
    Class.forName(DRIVER_CLASS_NAME);
} catch (ClassNotFoundException | LinkageError e) {
    throw new IllegalArgumentException(
        "Db2 JDBC driver " + DRIVER_CLASS_NAME + " not on classpath; add db2jcc jar to $SEATUNNEL_HOME/lib", e);
}

// verify driver presence before submitting the CDC job
try {
    Class.forName("com.ibm.db2.jcc.DB2Driver");
    System.out.println("Db2 JDBC driver OK");
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Copy db2jcc jar into $SEATUNNEL_HOME/lib and restart the cluster");
}

null

try {
    sourceFactory.createSource(context);
} catch (SQLException e) {
    if (e.getMessage() != null && e.getMessage().contains("No suitable driver")) {
        throw new IllegalStateException("Db2 JDBC driver missing — see 'Failed to load JDBC driver' warning");
    }
    throw e;
}

When it happens

Trigger: Db2IncrementalSourceFactory.createSource runs but DRIVER_CLASS_NAME cannot be loaded: the Db2 JDBC driver jar is absent from the classpath (the connector distribution does not bundle it due to licensing), the plugin/lib directory is misconfigured, or the class name is wrong.

Common situations: Deploying SeaTunnel without manually installing the db2jcc driver jar; custom classloader/plugin isolation preventing discovery; assembling a shaded build without com.ibm.db2:jcc; upgrading SeaTunnel and forgetting to re-copy driver jars.

Related errors

• Failed to load MySQL JDBC driver
• Failed to load JDBC driver {}
• Failed to load JDBC driver {}
• Error to discover tables:
• Error to check tables:

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/bd4c4d78434411ab. Report an issue: GitHub.