Why Your Java HttpClient Leaks Files and How to Fix It

Background and Problem Statement

When performing high‑concurrency network programming, failing to close resources properly can cause the number of open file descriptors (fd) to grow until the system runs out of handles, leading to errors such as "too many open files" and subsequent HTTP request failures.

A simple demo using HttpClient‑3.x to request a URL repeatedly demonstrates this issue. Under heavy load the process quickly reaches the default limit of 655350 open files.

Root‑Cause Analysis

Two main problems were identified in the original code:

Improper initialization : Creating new HttpClient() without specifying a connection manager defaults to SimpleHttpConnectionManager, whose alwaysClose flag is false. Consequently, even calling releaseConnection() does not actually close the underlying socket.

Missing releaseConnection call : The only call to method.releaseConnection() occurs inside the catch block, so in normal execution the connection is never released, causing connections to remain in CLOSE_WAIT state and consuming file descriptors.

Understanding Linux File Descriptors

Linux treats everything as a file, including sockets. Each HTTP request creates a socket, which consumes an fd. System limits are enforced at three levels: per‑process limits (viewed with ulimit -n), per‑user limits (configured in /etc/security/limits.conf), and the global kernel limit ( /proc/sys/fs/file‑max).

HttpClient 3.x Internals

The releaseConnection() method of HttpMethodBase first closes the response input stream, then calls HttpConnection.releaseConnection(). If alwaysClose is true, the connection is fully closed; otherwise only the input stream is closed, leaving the socket open.

Correct ways to close a 3.x client include:

Call method.releaseConnection() and then invoke SimpleHttpConnectionManager.shutdown() directly.

Call method.releaseConnection() and then SimpleHttpConnectionManager.closeIdleConnections(0).

Set the request header Connection: close and call method.releaseConnection() so the server also signals closure.

HttpClient 4.x Modern Usage

Version 4.x replaces the old API with CloseableHttpClient created via HttpClients.createDefault(). The default manager is PoolingHttpClientConnectionManager, which reuses connections and is thread‑safe.

Key classes and their responsibilities: CloseableHttpClient – abstract base for HTTP execution. InternalHttpClient – concrete implementation used by the factory. HttpResponseProxy – wraps the response and releases the underlying connection when close() is called. ConnectionHolder – holds the low‑level HttpConnection and performs the actual socket shutdown.

The close() method of HttpResponseProxy ultimately calls ConnectionHolder.releaseConnection(false), which closes the socket and removes the connection from the pool.

Connection Pool Configuration

private static volatile CloseableHttpClient instance;
static {
    PoolingHttpClientConnectionManager cm = new PoolingHttpClientConnectionManager();
    cm.setMaxTotal(200); // total connections
    cm.setDefaultMaxPerRoute(20); // per‑host limit
    RequestConfig requestConfig = RequestConfig.custom()
        .setConnectTimeout(1000)
        .setSocketTimeout(1000)
        .setConnectionRequestTimeout(1000)
        .build();
    instance = HttpClients.custom()
        .setConnectionManager(cm)
        .setDefaultRequestConfig(requestConfig)
        .build();
}

This configuration limits the total number of pooled connections and the maximum concurrent connections per target host, preventing a single service from monopolising all sockets.

Idle Connection Monitoring

Because the pool cannot always detect stale connections, a background thread should periodically close expired and idle connections:

public class IdleConnectionMonitorThread extends Thread {
    private final HttpClientConnectionManager connMgr;
    private volatile boolean shutdown;
    public IdleConnectionMonitorThread(HttpClientConnectionManager connMgr) {
        this.connMgr = connMgr;
    }
    @Override
    public void run() {
        try {
            while (!shutdown) {
                synchronized (this) { wait(5000); }
                connMgr.closeExpiredConnections();
                connMgr.closeIdleConnections(30, TimeUnit.SECONDS);
            }
        } catch (InterruptedException ex) {
            // log error
        }
    }
    public void shutdown() {
        shutdown = true;
        synchronized (this) { notifyAll(); }
    }
}

Starting this thread ensures that connections that have been idle for more than 30 seconds or have become invalid are removed from the pool.

Best Practices Summary

Always use a connection manager (preferably pooling) instead of the default SimpleHttpConnectionManager.

Call method.releaseConnection() (or close the CloseableHttpResponse) after each request.

Configure reasonable limits for total and per‑route connections.

Run an idle‑connection monitor to clean up stale sockets.

When using HttpClient 3.x, set alwaysClose=true or explicitly shut down the manager.

By following these guidelines, Java applications can avoid exhausting file descriptors and maintain stable high‑throughput HTTP communication.