apache/seatunnel · error · HiveConnectorException

INITIALIZE_HIVE_METASTORE_CLIENT_FAILED

INITIALIZE_HIVE_METASTORE_CLIENT_FAILED

Error message

Failed to initialize HiveMetaStoreClient [uris=${metastoreUri}, hiveSite=${hiveSitePath}]

What it means

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.

Source

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

        return hiveClient;
    }

    private IMetaStoreClient initializeClient() {
        this.hiveConf = buildHiveConf();
        try {
            if (kerberosEnabled) {
                return loginWithKerberos(hiveConf);
            }
            if (remoteUserEnabled) {
                return loginWithRemoteUser(hiveConf);
            }
            return createClient(hiveConf);
        } catch (Exception e) {
            String errMsg =
                    String.format(
                            "Failed to initialize HiveMetaStoreClient [uris=%s, hiveSite=%s]",
                            metastoreUri, hiveSitePath);
            throw new HiveConnectorException(
                    HiveConnectorErrorCode.INITIALIZE_HIVE_METASTORE_CLIENT_FAILED, errMsg, e);
        }
    }

    private IMetaStoreClient createClient(HiveConf hiveConf) throws Exception {
        String clientFactoryClassName = hiveConf.getTrimmed(METASTORE_CLIENT_FACTORY_CLASS);
        if (StringUtils.isNotBlank(clientFactoryClassName)) {
            return createClientFromFactory(hiveConf, clientFactoryClassName);
        }
        if (StringUtils.isBlank(hiveConf.getTrimmed("hive.metastore.uris"))) {
            throw new IllegalArgumentException(
                    "Either metastore_uri or hive.metastore.client.factory.class must be configured");
        }
        IMetaStoreClient retryingClient = tryCreateRetryingClient(hiveConf);
        if (retryingClient != null) {
            return retryingClient;
        }
        return new HiveMetaStoreClient(hiveConf);

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Check the wrapped cause (e) for the root error — connection refused vs auth vs missing file.
  2. Verify metastore_uri (thrift://host:9083) and that the Hive metastore service is running and reachable from all SeaTunnel nodes.
  3. Confirm hive-site.xml exists at hiveSitePath and is readable by the job process.
  4. Test connectivity: nc -vz <host> 9083 from a worker node.
  5. If using Kerberos, validate krb5.conf, keytab, and principal settings.

Example fix

// before
metastore_uri = "thrift://metastore-host:9084"
// after
metastore_uri = "thrift://metastore-host:9083"
Defensive patterns

Strategy: try-catch

Validate before calling

String uri = readonlyConfig.get(HiveOptions.METASTORE_URI);
if (uri != null) {
    java.net.URI u = java.net.URI.create(uri);
    try (java.net.Socket s = new java.net.Socket()) {
        s.connect(new java.net.InetSocketAddress(u.getHost(), u.getPort()), 3000);
    }
}

Try / catch

try {
    catalog.getClient();
} catch (HiveConnectorException e) {
    LOG.error("metastore init failed [uris/hiveSite in msg]; inspect cause", e.getCause());
    throw new IllegalStateException("Verify metastore_uri, hive-site.xml, and Kerberos setup", e);
}

Prevention

When it happens

Trigger: 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.

Common situations: Wrong metastore_uri host/port, metastore service down, hive-site.xml missing on workers, Kerberos keytab/principal misconfigured, firewall blocking thrift port 9083.

Related errors

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