apache/seatunnel · critical · IllegalStateException

Unable to load Hive metastore client factory ${clientFactory

Error message

Unable to load Hive metastore client factory ${clientFactoryClassName}. Make sure the factory and compatible Hive classes are available on the runtime classpath

What it means

Thrown by createClientFromFactory when the pluggable Hive metastore client factory class named by configuration cannot be loaded/instantiated at runtime. This happens on ReflectiveOperationException or LinkageError, meaning the factory class or the Hive client classes it depends on are absent from the runtime classpath, or are from an incompatible Hive version. The job fails fast because no metastore connection can be established.

Source

Thrown at seatunnel-connectors-v2/connector-hive/src/main/java/org/apache/seatunnel/connectors/seatunnel/hive/utils/HiveMetaStoreCatalog.java:207

                            hookLoader,
                            false,
                            new ConcurrentHashMap<String, Long>());
            if (!(client instanceof IMetaStoreClient)) {
                throw new IllegalStateException(
                        String.format(
                                "Hive metastore client factory %s returned an incompatible client",
                                clientFactoryClassName));
            }
            log.info("Using Hive metastore client factory {}", clientFactoryClassName);
            return (IMetaStoreClient) client;
        } catch (InvocationTargetException e) {
            throw new IllegalStateException(
                    String.format(
                            "Hive metastore client factory %s failed to create a client",
                            clientFactoryClassName),
                    e.getCause());
        } catch (ReflectiveOperationException | LinkageError e) {
            throw new IllegalStateException(
                    String.format(
                            "Unable to load Hive metastore client factory %s. Make sure the factory and compatible Hive classes are available on the runtime classpath",
                            clientFactoryClassName),
                    e);
        }
    }

    /**
     * Resolves an optional metastore factory from the runtime context before falling back to Hive's
     * configured class loader.
     */
    private static Class<?> loadClass(String className, HiveConf hiveConf)
            throws ClassNotFoundException {
        ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();
        if (contextClassLoader != null) {
            try {
                return Class.forName(className, true, contextClassLoader);
            } catch (ClassNotFoundException ignored) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify clientFactoryClassName in the config is the exact fully-qualified class name (check package and spelling).
2. Copy the jar containing the factory into the SeaTunnel connector plugin directory (connectors/ and its lib) on every node and restart.
3. Ensure Hive metastore client jars matching your Hive server version (e.g. hive-exec, hive-metastore, libfb303) are on the runtime classpath and not shaded away.
4. If a LinkageError occurs, rebuild the factory against the same Hive version the connector ships with, or use the built-in default client factory.
5. Run with -e local or check worker logs for the chained cause to see which class was missing.

Example fix

// before (config)
catalog {
  factory = "com.example.HiveMetastoreFactory" // class not on classpath
}

// after: deploy the jar then use exact FQCN
catalog {
  factory = "com.example.hive.MyHiveMetastoreClientFactory"
}

String cls = config.getClientFactoryClassName();
try {
    Class.forName(cls, false, Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Client factory not on classpath: " + cls, e);
}

When it happens

Trigger: Calling createClient -> createClientFromFactory with a clientFactoryClassName that does not exist on the classpath (typo, wrong package), the factory's jar is not in the plugin/connector directory, or the factory was compiled against a different Hive major version causing NoSuchMethodError/NoClassDefFoundError (LinkageError).

Common situations: Running SeaTunnel on a cluster where the Hive connector plugin directory lacks the custom factory jar; using a factory built for Hive 1.x/2.x with a runtime carrying Hive 3.x; misspelling the fully-qualified class name in the job config; shaded/uber-jar conflicts hiding org.apache.hadoop.hive classes.

Related errors

• method invoke failed, no such method '%s' in '%s'
• REFLECT_CLASS_OPERATION_FAILED
• CREATE_DRIVER_FAILED
• Failed to call factoryIdentifier method.
• RetryingMetaStoreClient found but no compatible getProxy met

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