{"record":{"id":"77bd6ce48badc682","repo":"apache/seatunnel","slug":"hive-metastore-client-factory-clientfactoryclass","errorCode":null,"errorMessage":"Hive metastore client factory ${clientFactoryClassName} returned an incompatible client","messagePattern":"Hive metastore client factory (.+?) returned an incompatible client","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-hive/src/main/java/org/apache/seatunnel/connectors/seatunnel/hive/utils/HiveMetaStoreCatalog.java","lineNumber":193,"sourceCode":"            Class<?> factoryClass = loadClass(clientFactoryClassName, hiveConf);\n            Object factory = factoryClass.getDeclaredConstructor().newInstance();\n            Method createClientMethod =\n                    factoryClass.getMethod(\n                            \"createMetaStoreClient\",\n                            HiveConf.class,\n                            HiveMetaHookLoader.class,\n                            boolean.class,\n                            ConcurrentHashMap.class);\n            HiveMetaHookLoader hookLoader = tableName -> null;\n            Object client =\n                    createClientMethod.invoke(\n                            factory,\n                            hiveConf,\n                            hookLoader,\n                            false,\n                            new ConcurrentHashMap<String, Long>());\n            if (!(client instanceof IMetaStoreClient)) {\n                throw new IllegalStateException(\n                        String.format(\n                                \"Hive metastore client factory %s returned an incompatible client\",\n                                clientFactoryClassName));\n            }\n            log.info(\"Using Hive metastore client factory {}\", clientFactoryClassName);\n            return (IMetaStoreClient) client;\n        } catch (InvocationTargetException e) {\n            throw new IllegalStateException(\n                    String.format(\n                            \"Hive metastore client factory %s failed to create a client\",\n                            clientFactoryClassName),\n                    e.getCause());\n        } catch (ReflectiveOperationException | LinkageError e) {\n            throw new IllegalStateException(\n                    String.format(\n                            \"Unable to load Hive metastore client factory %s. Make sure the factory and compatible Hive classes are available on the runtime classpath\",\n                            clientFactoryClassName),\n                    e);","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-hive/src/main/java/org/apache/seatunnel/connectors/seatunnel/hive/utils/HiveMetaStoreCatalog.java#L175-L211","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nhive.metastore.client.factory.class = com.custom.WrongFactory\n// after\nhive.metastore.client.factory.class = org.apache.hadoop.hive.metastore.MetastoreClientFactory","handlingStrategy":"validation","validationCode":"String cls = hiveConf.getTrimmed(\"hive.metastore.client.factory.class\");\nif (cls != null) {\n    Class<?> c = Class.forName(cls);\n    if (!org.apache.hadoop.hive.metastore.IMetaStoreClient.class.isAssignableFrom(c)\n            && !isKnownFactoryClass(c)) {\n        throw new IllegalArgumentException(cls + \" is not a valid metastore client factory\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    catalog.getClient();\n} catch (HiveConnectorException | IllegalStateException e) {\n    if (String.valueOf(e).contains(\"incompatible client\")) {\n        LOG.error(\"Factory returned non-IMetaStoreClient; align Hive client jars/version\", e);\n    }\n    throw e;\n}","preventionTips":["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"],"tags":["hive-metastore","reflection","type-mismatch"],"backgroundTag":"type-mismatch","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}