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.

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

• Col not found
• ColType or colName is null, colType
• File not found
• File not found
• 切分份数不能小于1. 此处:expectSliceNumber=

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

Appendix: 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)