{"record":{"id":"9fc3835ccaddb517","repo":"apache/seatunnel","slug":"unable-to-load-hive-metastore-client-factory-cli","errorCode":null,"errorMessage":"Unable to load Hive metastore client factory ${clientFactoryClassName}. Make sure the factory and compatible Hive classes are available on the runtime classpath","messagePattern":"Unable to load Hive metastore client factory (.+?)\\. Make sure the factory and compatible Hive classes are available on the runtime classpath","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"seatunnel-connectors-v2/connector-hive/src/main/java/org/apache/seatunnel/connectors/seatunnel/hive/utils/HiveMetaStoreCatalog.java","lineNumber":207,"sourceCode":"                            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);\n        }\n    }\n\n    /**\n     * Resolves an optional metastore factory from the runtime context before falling back to Hive's\n     * configured class loader.\n     */\n    private static Class<?> loadClass(String className, HiveConf hiveConf)\n            throws ClassNotFoundException {\n        ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();\n        if (contextClassLoader != null) {\n            try {\n                return Class.forName(className, true, contextClassLoader);\n            } catch (ClassNotFoundException ignored) {","sourceCodeStart":189,"sourceCodeEnd":225,"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#L189-L225","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Verify clientFactoryClassName in the config is the exact fully-qualified class name (check package and spelling).","Copy the jar containing the factory into the SeaTunnel connector plugin directory (connectors/ and its lib) on every node and restart.","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.","If a LinkageError occurs, rebuild the factory against the same Hive version the connector ships with, or use the built-in default client factory.","Run with -e local or check worker logs for the chained cause to see which class was missing."],"exampleFix":"// before (config)\ncatalog {\n  factory = \"com.example.HiveMetastoreFactory\" // class not on classpath\n}\n\n// after: deploy the jar then use exact FQCN\ncatalog {\n  factory = \"com.example.hive.MyHiveMetastoreClientFactory\"\n}","handlingStrategy":"validation","validationCode":"String cls = config.getClientFactoryClassName();\ntry {\n    Class.forName(cls, false, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Client factory not on classpath: \" + cls, e);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use the built-in default factory unless a custom one is truly needed","Deploy factory jars to every node's plugin directory and pin Hive versions consistently","Smoke-test the job with -e local before cluster submission"],"tags":["hive","classpath","reflection","connector"],"backgroundTag":"class-not-found","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"}