apache/seatunnel · error · IllegalStateException

Hive metastore client factory ${clientFactoryClassName} retu

Error message

Hive metastore client factory ${clientFactoryClassName} returned an incompatible client

What it means

When a custom metastore client factory class is configured, createClientFromFactory reflectively invokes the factory and verifies the returned object implements IMetaStoreClient. If the produced object is of an unexpected type, it throws this IllegalStateException, since a non-IMetaStoreClient result cannot be used by the catalog.

Source

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

            Class<?> factoryClass = loadClass(clientFactoryClassName, hiveConf);
            Object factory = factoryClass.getDeclaredConstructor().newInstance();
            Method createClientMethod =
                    factoryClass.getMethod(
                            "createMetaStoreClient",
                            HiveConf.class,
                            HiveMetaHookLoader.class,
                            boolean.class,
                            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);

View on GitHub (pinned to cf67b549a7)

Solutions

Check the configured factory class matches your Hive client version (e.g. org.apache.hadoop.hive.metastore.MetastoreClientFactory vs standalone-metastore variants).
Ensure the factory's create method returns an IMetaStoreClient implementation.
Align the Hive metastore client dependency version with the server's Hive version.
Remove the factory class config and rely on metastore_uri (default RetryingMetaStoreClient path) instead.

Example fix

// before
hive.metastore.client.factory.class = com.custom.WrongFactory
// after
hive.metastore.client.factory.class = org.apache.hadoop.hive.metastore.MetastoreClientFactory

Defensive patterns

Strategy: validation

Validate before calling

String cls = hiveConf.getTrimmed("hive.metastore.client.factory.class");
if (cls != null) {
    Class<?> c = Class.forName(cls);
    if (!org.apache.hadoop.hive.metastore.IMetaStoreClient.class.isAssignableFrom(c)
            && !isKnownFactoryClass(c)) {
        throw new IllegalArgumentException(cls + " is not a valid metastore client factory");
    }
}

Try / catch

try {
    catalog.getClient();
} catch (HiveConnectorException | IllegalStateException e) {
    if (String.valueOf(e).contains("incompatible client")) {
        LOG.error("Factory returned non-IMetaStoreClient; align Hive client jars/version", e);
    }
    throw e;
}

Prevention

Match the factory class to your Hive client version
Avoid custom factories unless they return IMetaStoreClient
Prefer the default metastore_uri path over custom factories

When it happens

Trigger: Configuring hive.metastore.client.factory.class to a class whose newInstance/RetryingMetaStoreClient-style invocation returns an object that is not an IMetaStoreClient — usually a wrong or custom class implementing the wrong interface/version.

Common situations: Upgrading Hive where MetastoreClientFactory APIs changed, pointing at a factory class from a different Hive version, or a user-written factory returning a wrapper type.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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