redis/jedis · critical · JedisConnectionException

Failed to create socket.

Error message

Failed to create socket.

What it means

Jedis wraps any non-JedisConnectionException thrown while creating the TCP socket into a JedisConnectionException with the message 'Failed to create socket.', preserving the original exception as the cause. This happens in DefaultJedisSocketFactory.createSocket when the underlying SocketChannel.open/socket/connect/timeout configuration calls fail. It signals that no connection to the Redis server could be established at the socket level, before any Redis protocol exchange occurs.

Solutions

1. Verify the Redis server is running and reachable: run 'redis-cli -h <host> -p <port> ping' from the client machine.
2. Check the HostAndPort/host/port configuration passed to the Jedis client or pool for typos and environment-specific values.
3. Inspect the cause chain (ex.getCause()) to distinguish DNS failure, connection refused, and timeout, and fix accordingly.
4. Check network/firewall/DNS (security groups, VPC, k8s service) between client and server.
5. Increase socketTimeout/connectionTimeout if timeouts occur under load or on high-latency links.
6. Enable retryable executor or wrap client usage with retry/backoff for transient network failures.

Example fix

// before
JedisClientConfig config = DefaultJedisClientConfig.builder().socketTimeoutMillis(50).build();
Jedis jedis = new Jedis("redis.internal", 6379, config); // fails on slow link

// after
JedisClientConfig config = DefaultJedisClientConfig.builder()
    .connectionTimeoutMillis(2000)
    .socketTimeoutMillis(2000)
    .build();
Jedis jedis = new Jedis(HostAndPort.from("redis.internal:6379"), config);

// pre-flight check before creating the client
try (java.net.Socket s = new java.net.Socket()) {
  s.connect(new java.net.InetSocketAddress(host, port), 2000); // throws if unreachable
}

try {
  jedis = new Jedis(hostAndPort, config);
} catch (JedisConnectionException e) {
  Throwable cause = e.getCause();
  if (cause instanceof java.net.UnknownHostException) {
    // fix DNS / hostname
  } else if (cause instanceof java.net.ConnectException) {
    // server down or port blocked
  } else if (cause instanceof java.net.SocketTimeoutException) {
    // retry with backoff or raise timeout
  }
  throw e;
}

When it happens

Trigger: Calling any Jedis connection/command API when the target host cannot be resolved (UnknownHostException), the port is unreachable (ConnectException: connection refused), a socket timeout elapses (SocketTimeoutException), the socket is interrupted, or socket options (e.g. tcpNoDelay/keepAlive via SocketFactory) throw while configuring the socket.

Common situations: Redis server not running or listening on a different port; wrong host/port in configuration; DNS misconfiguration in containers/Kubernetes; firewall or security-group blocking the port; overly aggressive soTimeout/connection timeout; network partitions or node failover in cluster setups.

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

• All configured databases are unhealthy. Cannot initialize…
• It seems like server has closed the connection.
• Unexpected end of stream.
• Attempting to write to a broken connection.
• Attempting to read from a broken connection.

AI-assisted analysis of redis/jedis@6dac31d4c2 (2026-09-08). Data as JSON: /api/errors/b2956628e4c1c85d. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/redis/clients/jedis/DefaultJedisSocketFactory.java:133

  public Socket createSocket() throws JedisConnectionException {
    Socket socket = null;
    try {
      HostAndPort _hostAndPort = getSocketHostAndPort();
      socket = connectToFirstSuccessfulHost(_hostAndPort);
      socket.setSoTimeout(socketTimeout);

      if (ssl || sslOptions != null) {
        socket = createSslSocket(_hostAndPort, socket);
      }

      return socket;

    } catch (Exception ex) {
      IOUtils.closeQuietly(socket);
      if (ex instanceof JedisConnectionException) {
        throw (JedisConnectionException) ex;
      } else {
        throw new JedisConnectionException("Failed to create socket.", ex);
      }
    }
  }

  /**
   * ssl enable check is done before this.
   */
  private Socket createSslSocket(HostAndPort _hostAndPort, Socket socket) throws IOException, GeneralSecurityException {

    Socket plainSocket = socket;

    SSLSocketFactory _sslSocketFactory;
    SSLParameters _sslParameters;

    if (sslOptions != null) {

      SSLContext _sslContext = sslOptions.createSslContext();
      _sslSocketFactory = _sslContext.getSocketFactory();

View on GitHub (pinned to 6dac31d4c2)