{"record":{"id":"1a00ef71dc93c6c0","repo":"apache/seatunnel","slug":"initialize-hive-metastore-client-failed","errorCode":"INITIALIZE_HIVE_METASTORE_CLIENT_FAILED","errorMessage":"Failed to initialize HiveMetaStoreClient [uris=${metastoreUri}, hiveSite=${hiveSitePath}]","messagePattern":"Failed to initialize HiveMetaStoreClient \\[uris=(.+?), hiveSite=(.+?)\\]","errorType":"error_code","errorClass":"HiveConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-hive/src/main/java/org/apache/seatunnel/connectors/seatunnel/hive/utils/HiveMetaStoreCatalog.java","lineNumber":148,"sourceCode":"        return hiveClient;\n    }\n\n    private IMetaStoreClient initializeClient() {\n        this.hiveConf = buildHiveConf();\n        try {\n            if (kerberosEnabled) {\n                return loginWithKerberos(hiveConf);\n            }\n            if (remoteUserEnabled) {\n                return loginWithRemoteUser(hiveConf);\n            }\n            return createClient(hiveConf);\n        } catch (Exception e) {\n            String errMsg =\n                    String.format(\n                            \"Failed to initialize HiveMetaStoreClient [uris=%s, hiveSite=%s]\",\n                            metastoreUri, hiveSitePath);\n            throw new HiveConnectorException(\n                    HiveConnectorErrorCode.INITIALIZE_HIVE_METASTORE_CLIENT_FAILED, errMsg, e);\n        }\n    }\n\n    private IMetaStoreClient createClient(HiveConf hiveConf) throws Exception {\n        String clientFactoryClassName = hiveConf.getTrimmed(METASTORE_CLIENT_FACTORY_CLASS);\n        if (StringUtils.isNotBlank(clientFactoryClassName)) {\n            return createClientFromFactory(hiveConf, clientFactoryClassName);\n        }\n        if (StringUtils.isBlank(hiveConf.getTrimmed(\"hive.metastore.uris\"))) {\n            throw new IllegalArgumentException(\n                    \"Either metastore_uri or hive.metastore.client.factory.class must be configured\");\n        }\n        IMetaStoreClient retryingClient = tryCreateRetryingClient(hiveConf);\n        if (retryingClient != null) {\n            return retryingClient;\n        }\n        return new HiveMetaStoreClient(hiveConf);","sourceCodeStart":130,"sourceCodeEnd":166,"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#L130-L166","documentation":"HiveMetaStoreCatalog.initializeClient builds a HiveConf from metastore_uri and/or the hive-site path and creates an IMetaStoreClient. Any exception during setup (bad URI, missing hive-site.xml, Kerberos failure, network error to the metastore) is wrapped in HiveConnectorException INITIALIZE_HIVE_METASTORE_CLIENT_FAILED with the URIs and hive-site path in the message and the original cause attached.","triggerScenarios":"Calling initializeClient (via getClient) when the metastore URIs are unreachable/malformed, hive-site.xml cannot be read, Kerberos/remote-user login fails, or createClient throws.","commonSituations":"Wrong metastore_uri host/port, metastore service down, hive-site.xml missing on workers, Kerberos keytab/principal misconfigured, firewall blocking thrift port 9083.","solutions":["Check the wrapped cause (e) for the root error — connection refused vs auth vs missing file.","Verify metastore_uri (thrift://host:9083) and that the Hive metastore service is running and reachable from all SeaTunnel nodes.","Confirm hive-site.xml exists at hiveSitePath and is readable by the job process.","Test connectivity: nc -vz <host> 9083 from a worker node.","If using Kerberos, validate krb5.conf, keytab, and principal settings."],"exampleFix":"// before\nmetastore_uri = \"thrift://metastore-host:9084\"\n// after\nmetastore_uri = \"thrift://metastore-host:9083\"","handlingStrategy":"try-catch","validationCode":"String uri = readonlyConfig.get(HiveOptions.METASTORE_URI);\nif (uri != null) {\n    java.net.URI u = java.net.URI.create(uri);\n    try (java.net.Socket s = new java.net.Socket()) {\n        s.connect(new java.net.InetSocketAddress(u.getHost(), u.getPort()), 3000);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    catalog.getClient();\n} catch (HiveConnectorException e) {\n    LOG.error(\"metastore init failed [uris/hiveSite in msg]; inspect cause\", e.getCause());\n    throw new IllegalStateException(\"Verify metastore_uri, hive-site.xml, and Kerberos setup\", e);\n}","preventionTips":["Verify metastore reachability (thrift port 9083) from all worker nodes before job submission","Ship hive-site.xml consistently to every node","Validate Kerberos krb5.conf/keytab paths when security is enabled"],"tags":["hive-metastore","connection","initialization"],"backgroundTag":"module-init-failed","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}