apache/seatunnel · error · TDengineConnectorException

LOAD_DRIVER_FAILED

LOAD_DRIVER_FAILED

Error message

Fail to create driver of class 

What it means

checkDriverExist() in TDengineUtil fails to load and register the TDengine JDBC driver class. The driver class could not be found via the context ClassLoader or could not be instantiated/registered with DriverManager.

Source

Thrown at seatunnel-connectors-v2/connector-tdengine/src/main/java/org/apache/seatunnel/connectors/seatunnel/tdengine/utils/TDengineUtil.java:52

            DriverManager.getDriver(jdbcUrl);
        } catch (SQLException e) {
            log.warn("no available driver found for this {}, waiting for it to load", jdbcUrl);
        }

        String driverName;
        if (jdbcUrl.startsWith("jdbc:TAOS-RS://")) {
            driverName = "com.taosdata.jdbc.rs.RestfulDriver";
        } else {
            driverName = "com.taosdata.jdbc.TSDBDriver";
        }

        try {
            Class<?> clazz =
                    Class.forName(driverName, true, Thread.currentThread().getContextClassLoader());
            Driver driver = (Driver) clazz.getDeclaredConstructor().newInstance();
            DriverManager.registerDriver(driver);
        } catch (Exception ex) {
            throw new TDengineConnectorException(
                    TDengineConnectorErrorCode.LOAD_DRIVER_FAILED,
                    "Fail to create driver of class " + driverName,
                    ex);
        }
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add taos-jdbcdriver jar to $SEATUNNEL_HOME/connectors/ (or connector plugin dir) or run sh bin/install-plugin.sh.
2. Confirm the driverName in the message matches a class present in the jar (e.g. com.taosdata.jdbc.TSDBDriver or RSDBDriver).
3. If using native connectivity, also install TDengine client libraries matching the server version; otherwise use the restful driver.
4. Rebuild/repackage with the driver dependency included and verify plugin packaging excludes it from shading conflicts.

Example fix

// before
# ls $SEATUNNEL_HOME/connectors | grep -i taos
# (no taos-jdbcdriver jar)
// after
sh bin/install-plugin.sh
# or manually copy: cp taos-jdbcdriver-3.x.x-dist.jar $SEATUNNEL_HOME/connectors/

// Verify driver presence before job
Class.forName("com.taosdata.jdbc.TSDBDriver", true,
    Thread.currentThread().getContextClassLoader());

try {
    source.open();
} catch (TDengineConnectorException e) {
    if (e.getErrorCode() == TDengineConnectorErrorCode.LOAD_DRIVER_FAILED) {
        log.error("taos-jdbcdriver missing from classpath: {}", e.getCause());
    }
    throw e;
}

When it happens

Trigger: Class.forName(driverName, true, contextClassLoader) throws ClassNotFoundException, or newInstance()/registerDriver throws, because the taos-jdbcdriver jar is absent from the plugin classpath.

Common situations: TDengine connector jar installed without the JDBC driver dependency; using $SEATUNNEL_HOME/connectors without running install-plugin.sh; shaded/assembly packaging missing the driver; classloader isolation in cluster deployments.

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

• DRIVER_NOT_FOUND
• CONNECT_FAILED
• CLASS_NOT_FOUND
• CREATE_DRIVER_FAILED
• Failed to load JDBC driver {}

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