{"record":{"id":"b2956628e4c1c85d","repo":"redis/jedis","slug":"failed-to-create-socket","errorCode":null,"errorMessage":"Failed to create socket.","messagePattern":"Failed to create socket\\.","errorType":"exception","errorClass":"JedisConnectionException","httpStatus":null,"severity":"critical","filePath":"src/main/java/redis/clients/jedis/DefaultJedisSocketFactory.java","lineNumber":133,"sourceCode":"  public Socket createSocket() throws JedisConnectionException {\n    Socket socket = null;\n    try {\n      HostAndPort _hostAndPort = getSocketHostAndPort();\n      socket = connectToFirstSuccessfulHost(_hostAndPort);\n      socket.setSoTimeout(socketTimeout);\n\n      if (ssl || sslOptions != null) {\n        socket = createSslSocket(_hostAndPort, socket);\n      }\n\n      return socket;\n\n    } catch (Exception ex) {\n      IOUtils.closeQuietly(socket);\n      if (ex instanceof JedisConnectionException) {\n        throw (JedisConnectionException) ex;\n      } else {\n        throw new JedisConnectionException(\"Failed to create socket.\", ex);\n      }\n    }\n  }\n\n  /**\n   * ssl enable check is done before this.\n   */\n  private Socket createSslSocket(HostAndPort _hostAndPort, Socket socket) throws IOException, GeneralSecurityException {\n\n    Socket plainSocket = socket;\n\n    SSLSocketFactory _sslSocketFactory;\n    SSLParameters _sslParameters;\n\n    if (sslOptions != null) {\n\n      SSLContext _sslContext = sslOptions.createSslContext();\n      _sslSocketFactory = _sslContext.getSocketFactory();","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/redis/jedis/blob/6dac31d4c224fb3257c216f3985340c6f500cdcb/src/main/java/redis/clients/jedis/DefaultJedisSocketFactory.java#L115-L151","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the Redis server is running and reachable: run 'redis-cli -h <host> -p <port> ping' from the client machine.","Check the HostAndPort/host/port configuration passed to the Jedis client or pool for typos and environment-specific values.","Inspect the cause chain (ex.getCause()) to distinguish DNS failure, connection refused, and timeout, and fix accordingly.","Check network/firewall/DNS (security groups, VPC, k8s service) between client and server.","Increase socketTimeout/connectionTimeout if timeouts occur under load or on high-latency links.","Enable retryable executor or wrap client usage with retry/backoff for transient network failures."],"exampleFix":"// before\nJedisClientConfig config = DefaultJedisClientConfig.builder().socketTimeoutMillis(50).build();\nJedis jedis = new Jedis(\"redis.internal\", 6379, config); // fails on slow link\n\n// after\nJedisClientConfig config = DefaultJedisClientConfig.builder()\n    .connectionTimeoutMillis(2000)\n    .socketTimeoutMillis(2000)\n    .build();\nJedis jedis = new Jedis(HostAndPort.from(\"redis.internal:6379\"), config);","handlingStrategy":"try-catch","validationCode":"// pre-flight check before creating the client\ntry (java.net.Socket s = new java.net.Socket()) {\n  s.connect(new java.net.InetSocketAddress(host, port), 2000); // throws if unreachable\n}","typeGuard":null,"tryCatchPattern":"try {\n  jedis = new Jedis(hostAndPort, config);\n} catch (JedisConnectionException e) {\n  Throwable cause = e.getCause();\n  if (cause instanceof java.net.UnknownHostException) {\n    // fix DNS / hostname\n  } else if (cause instanceof java.net.ConnectException) {\n    // server down or port blocked\n  } else if (cause instanceof java.net.SocketTimeoutException) {\n    // retry with backoff or raise timeout\n  }\n  throw e;\n}","preventionTips":["Always inspect getCause() on JedisConnectionException to identify the socket-level root cause.","Health-check host/port with a lightweight TCP connect or redis-cli PING before starting the client.","Use realistic connectionTimeout/socketTimeout values for your network latency.","Configure a retryable CommandExecutor or wrap client creation in retry with backoff for transient failures.","Externalize host/port per environment and validate configuration at startup."],"tags":["network","socket","connection","redis"],"backgroundTag":"connection-refused","analyzedSha":"6dac31d4c224fb3257c216f3985340c6f500cdcb","analyzedAt":"2026-09-08T04:55:01.204Z","contentChangedAt":"2026-09-08T04:55:01.204Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}