apache/seatunnel · error · IllegalStateException

Hive metastore client factory ${clientFactoryClassName} fail

Error message

Hive metastore client factory ${clientFactoryClassName} failed to create a client

What it means

createClientFromFactory invokes the configured client factory reflectively. If the factory method itself throws (InvocationTargetException), a reflective failure occurs (ReflectiveOperationException), or the factory class cannot be loaded (LinkageError), it wraps the problem in an IllegalStateException stating the factory failed to create a client — with the underlying cause (e.getCause() for invocation failures) attached.

Source

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

                            ConcurrentHashMap.class);
            HiveMetaHookLoader hookLoader = tableName -> null;
            Object client =
                    createClientMethod.invoke(
                            factory,
                            hiveConf,
                            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)

View on GitHub (pinned to cf67b549a7)

Solutions

Read the chained cause (getCause) for the real failure: ClassNotFoundException vs NoSuchMethodError vs factory runtime error.
Fix the fully-qualified factory class name in the config.
Ensure the correct Hive client jars are in the SeaTunnel plugin/connectors directory (no mixed Hive versions).
Fall back to the standard path: unset the factory class and set metastore_uri instead.

Example fix

// before
hive.metastore.client.factory.class = org.apache.hive.metastore.NonExistentFactory
// after (use URI-based client)
metastore_uri = "thrift://metastore:9083"

Defensive patterns

Strategy: try-catch

Validate before calling

String cls = hiveConf.getTrimmed("hive.metastore.client.factory.class");
if (cls != null) {
    try { Class.forName(cls, false, Thread.currentThread().getContextClassLoader()); }
    catch (Throwable t) { throw new IllegalArgumentException("factory class not on classpath: " + cls); }
}

Try / catch

try {
    catalog.getClient();
} catch (IllegalStateException e) {
    LOG.error("Factory failed to create client; root cause:", e.getCause());
    throw new IllegalStateException("Fix factory class/jars or use metastore_uri instead", e);
}

Prevention

Verify the exact fully-qualified factory class name against your Hive version
Ensure Hive client jars are present and not version-mixed in the plugin directory
Read e.getCause() (NoSuchMethodError/ClassNotFoundException) to pinpoint jar conflicts

When it happens

Trigger: Calling createClient when the configured factory class does not exist, cannot be loaded (missing jar/conflicting Hive versions), its constructor/method throws at runtime, or it fails wiring dependencies (hook loader, conf).

Common situations: Factory class typo in config, hive-exec/standalone-metastore jars missing from the plugin dir, NoSuchMethodError from mixed Hive versions, or factory throwing during initialization (e.g. bad conf).

Related errors

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