prestodb/presto · critical · TTransportException

TTransportException

Error message

TTransportException

What it means

Transport.createRaw opens a Thrift socket transport to the Hive Metastore host. On connection failure the underlying IOException is caught and rethrown as a TTransportException, then rewriteException prefixes the message with the target host:port. This is the standard 'cannot reach the Metastore' error: DNS failure, refused connection, timeout, or TLS handshake problems all surface here as TTransportException.

Source

Thrown at presto-hive-metastore/src/main/java/com/facebook/presto/hive/metastore/thrift/Transport.java:88

            socket.setSoTimeout(timeoutMillis);

            if (sslContext.isPresent()) {
                // SSL will connect to the SOCKS address when present
                HostAndPort sslConnectAddress = socksProxy.orElse(address);

                socket = sslContext.get().getSocketFactory().createSocket(socket, sslConnectAddress.getHost(), sslConnectAddress.getPort(), true);
            }
            return new TSocket(socket);
        }
        catch (Throwable t) {
            // something went wrong, close the socket and rethrow
            try {
                socket.close();
            }
            catch (IOException e) {
                t.addSuppressed(e);
            }
            throw new TTransportException(t);
        }
    }

    private static TTransportException rewriteException(TTransportException e, HostAndPort address)
    {
        return new TTransportException(e.getType(), String.format("%s: %s", address, e.getMessage()), e);
    }

    @VisibleForTesting
    static class TTransportWrapper
            extends TTransport
    {
        private final TTransport transport;
        private final HostAndPort address;

        TTransportWrapper(TTransport transport, HostAndPort address)
        {
            this.transport = transport;

View on GitHub (pinned to 55bb57d202)

Solutions

1. Verify the Metastore service is running and listening on the configured host:port (nc -vz host 9083)
2. Check hive.metastore.uri in the catalog properties for typos (thrift://host:9083) and DNS resolution of the host
3. Check network/firewall/security-group rules between Presto coordinator/worker and the Metastore
4. Inspect Metastore service logs; restart the Metastore if it is hung, and review thrift transport timeouts/TLS settings

Example fix

// before
hive.metastore.uri=thrift://metastore-internal:9084
// after (correct host/port, service reachable)
hive.metastore.uri=thrift://metastore.internal.example.com:9083

// pre-flight reachability check before creating the transport
HostAndPort addr = HostAndPort.fromString(metastoreUri.getHost());
try (Socket s = new Socket()) {
    s.connect(new InetSocketAddress(addr.getHost(), addr.getPort()), 3000); // fails fast if unreachable
} catch (IOException e) {
    throw new PrestoException(HIVE_METASTORE_ERROR, "Metastore unreachable at " + addr, e);
}

boolean isMetastoreUriReachable(URI uri) {
    try (Socket s = new Socket()) {
        s.connect(new InetSocketAddress(uri.getHost(), uri.getPort() == -1 ? 9083 : uri.getPort()), 3000);
        return true;
    } catch (IOException e) { return false; }
}

// retry with backoff on TTransportException, then surface address
int attempts = 3;
for (int i = 1; i <= attempts; i++) {
    try {
        return Transport.createRaw(...);
    } catch (TTransportException e) {
        if (i == attempts) throw new PrestoException(HIVE_METASTORE_ERROR,
            "Cannot connect to metastore (see cause for host)", e);
        Thread.sleep(1000L * i);
    }
}

When it happens

Trigger: Calling createRaw/rawTransport when the Metastore URI host is unreachable: connection refused (service down), UnknownHost (bad DNS/hostname in hive.metastore.uri), connect timeout (firewall/security group), or TLS failure on thrifts:// URIs.

Common situations: Metastore service stopped or restarting; wrong host/port in catalog properties (hive.metastore.uri); Kubernetes/network policy blocking the port; DNS misconfiguration; Kerberos/TLS handshake issues on port 9083/10000.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• Failed connecting to Hive metastore: ${addresses}
• HIVE_METASTORE_ERROR
• GrantRevokeResponse missing success field
• NATIVEPLANCHECKER_CONNECTION_ERROR
• Request to remote Presto server failed

AI-assisted analysis of prestodb/presto@55bb57d202 (2026-09-04). Data as JSON: /api/errors/47d8e02e1ce9d738. Report an issue: GitHub.