{"record":{"id":"bd4c4d78434411ab","repo":"apache/seatunnel","slug":"failed-to-load-jdbc-driver","errorCode":null,"errorMessage":"Failed to load JDBC driver {}","messagePattern":"Failed to load JDBC driver (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-db2/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/db2/source/Db2IncrementalSourceFactory.java","lineNumber":113,"sourceCode":"                        StartupMode.INITIAL,\n                        SourceOptions.EXACTLY_ONCE)\n                .build();\n    }\n\n    @Override\n    public Class<? extends SeaTunnelSource> getSourceClass() {\n        return Db2IncrementalSource.class;\n    }\n\n    @Override\n    public <T, SplitT extends SourceSplit, StateT extends Serializable>\n            TableSource<T, SplitT, StateT> createSource(TableSourceFactoryContext context) {\n        return () -> {\n            // Load the JDBC driver in to DriverManager\n            try {\n                Class.forName(DRIVER_CLASS_NAME);\n            } catch (Exception e) {\n                log.warn(\"Failed to load JDBC driver {}\", DRIVER_CLASS_NAME, e);\n            }\n            List<CatalogTable> catalogTables =\n                    CatalogTableUtil.getCatalogTables(\n                            context.getOptions(), context.getClassLoader());\n            Optional<List<JdbcSourceTableConfig>> tableConfigs =\n                    context.getOptions()\n                            .getOptional(Db2IncrementalSourceOptions.TABLE_NAMES_CONFIG);\n            if (tableConfigs.isPresent()) {\n                catalogTables =\n                        CatalogTableUtils.mergeCatalogTableConfig(\n                                catalogTables,\n                                tableConfigs.get(),\n                                text -> TablePath.of(text, true));\n            }\n            return new Db2IncrementalSource(context.getOptions(), catalogTables);\n        };\n    }\n}","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-cdc/connector-cdc-db2/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/db2/source/Db2IncrementalSourceFactory.java#L95-L131","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Add com.ibm.db2:jcc as a dependency in your own shaded distribution build if you assemble SeaTunnel yourself.","Verify the configured driver class name matches the jar you installed (com.ibm.db2.jcc.DB2Driver).","Confirm resolution by checking the warning's stack trace is gone and a test JDBC connection to Db2 succeeds with the same classpath."],"exampleFix":"// before: driver jar missing -> warning at createSource, connect fails later\ntry {\n    Class.forName(DRIVER_CLASS_NAME);\n} catch (Exception e) {\n    log.warn(\"Failed to load JDBC driver {}\", DRIVER_CLASS_NAME, e);\n}\n// after: fail fast with an actionable message\ntry {\n    Class.forName(DRIVER_CLASS_NAME);\n} catch (ClassNotFoundException | LinkageError e) {\n    throw new IllegalArgumentException(\n        \"Db2 JDBC driver \" + DRIVER_CLASS_NAME + \" not on classpath; add db2jcc jar to $SEATUNNEL_HOME/lib\", e);\n}","handlingStrategy":"validation","validationCode":"// verify driver presence before submitting the CDC job\ntry {\n    Class.forName(\"com.ibm.db2.jcc.DB2Driver\");\n    System.out.println(\"Db2 JDBC driver OK\");\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Copy db2jcc jar into $SEATUNNEL_HOME/lib and restart the cluster\");\n}","typeGuard":"null","tryCatchPattern":"try {\n    sourceFactory.createSource(context);\n} catch (SQLException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"No suitable driver\")) {\n        throw new IllegalStateException(\"Db2 JDBC driver missing — see 'Failed to load JDBC driver' warning\");\n    }\n    throw e;\n}","preventionTips":["Ship db2jcc.jar in $SEATUNNEL_HOME/lib on every node; it is not bundled with the distribution.","Pin a JCC driver version compatible with your Db2 server and re-copy it after SeaTunnel upgrades.","Test a plain JDBC connection with the same classpath before submitting CDC jobs.","Check createSource logs for this warning after every deployment."],"tags":["jdbc","db2","classpath","driver-loading"],"backgroundTag":"class-not-found","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}