alibaba/DataX · critical · RuntimeException

faild load org.apache.phoenix.jdbc.PhoenixDriver

Error message

faild load org.apache.phoenix.jdbc.PhoenixDriver

What it means

RuntimeException (with cause) from a static initializer in HbaseSQLHelper: Class.forName("org.apache.phoenix.jdbc.PhoenixDriver") threw — classloading failure for the Phoenix JDBC driver. Because it is a static-init failure, the exception surfaces as ExceptionInInitializerError on first use of the class and the class is then unusable for the rest of the JVM run.

Source

Thrown at hbase11xsqlreader/src/main/java/com/alibaba/datax/plugin/reader/hbase11xsqlreader/HbaseSQLHelper.java:39

import org.apache.phoenix.schema.SaltingUtil;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.io.IOException;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.util.*;


public class HbaseSQLHelper {
    private static final Logger LOG = LoggerFactory.getLogger(HbaseSQLHelper.class);

    static {
        try {
            Class.forName("org.apache.phoenix.jdbc.PhoenixDriver");
        } catch (Throwable t) {
            throw new RuntimeException("faild load org.apache.phoenix.jdbc.PhoenixDriver", t);
        }
    }

    public static org.apache.hadoop.conf.Configuration generatePhoenixConf(HbaseSQLReaderConfig readerConfig) {
        org.apache.hadoop.conf.Configuration conf = new org.apache.hadoop.conf.Configuration();

        String table = readerConfig.getTableName();
        List<String> columns = readerConfig.getColumns();
        String zkUrl = readerConfig.getZkUrl();

        PhoenixConfigurationUtil.setInputClass(conf, PhoenixRecordWritable.class);

        PhoenixConfigurationUtil.setInputTableName(conf, readerConfig.getSchema()+"."+table);

        if (!columns.isEmpty()) {
            PhoenixConfigurationUtil.setSelectColumnNames(conf, columns.toArray(new String[columns.size()]));
        }
        if(Objects.nonNull(readerConfig.getWhere())){

View on GitHub (pinned to 80ec23d5c5)

Solutions

1. Check the Throwable cause in the stack trace (NoClassDefFoundError names the missing class).
2. Add the phoenix-client jar matching your HBase cluster version into hbase11xsqlreader/libs (plugin-local classloader).
3. Resolve dependency conflicts: keep DataX core libs on the shared classpath and Phoenix/HBase deps inside the plugin directory.
4. Re-download/verify the jar if corrupted (jar tf phoenix-*.jar).

try {
    Class.forName("org.apache.phoenix.jdbc.PhoenixDriver");
} catch (Throwable t) {
    throw new IllegalStateException("Phoenix client jar missing/incompatible in hbase11xsqlreader libs: " + t);
}

try {
    HbaseSQLHelper.init(...);
} catch (ExceptionInInitializerError e) {
    // static init already failed once; report classpath problem and restart JVM after fixing jars
}

When it happens

Trigger: First access to any HbaseSQLHelper member when org.apache.phoenix.jdbc.PhoenixDriver cannot be loaded: phoenix jar absent from the hbase11xsqlreader plugin's classpath, or present but its transitive dependencies (HBase/Hadoop/guava etc.) conflict with the versions bundled in DataX's lib directory.

Common situations: Deploying the plugin without putting the matching phoenix-client jar into the plugin dir; mixing Phoenix 4.x client with an incompatible HBase/Hadoop version on DataX's shared lib; jar corrupted or truncated during upload; running on a JDK whose classloader blocks the driver.

Related errors

• ColType or colName is null, colType : ${colType} , colName :
• Col {} not found
• File not found: ${name}
• File not found: ${name}
• CONFIG_ERROR

AI-assisted analysis of alibaba/DataX@80ec23d5c5 (2026-08-14). Data as JSON: /api/errors/1528c813a9ae01fe. Report an issue: GitHub.