redis/jedis · error · IllegalStateException

HostAndPort is required when no socketFactory is provided

Error message

HostAndPort is required when no socketFactory is provided

What it means

ConnectionFactory.createDefaultSocketFactory() throws IllegalStateException when neither a hostAndPort nor a custom socketFactory was supplied. Without one of them the client has no target endpoint to open a socket to, so builder validation fails at build() time.

Solutions

Call .hostAndPort("localhost", 6379) (or hostAndPort(HostAndPort)) on the builder
Provide a custom javax.net.SocketFactory via .socketFactory(...) for socket-based connections
Fix the source of the null host variable (missing env var/config property) before building

Example fix

// before
RedisClient client = RedisClient.builder()
    .clientConfig(cfg).build(); // IllegalStateException
// after
RedisClient client = RedisClient.builder()
    .hostAndPort("localhost", 6379)
    .clientConfig(cfg).build();

Defensive patterns

Strategy: validation

Validate before calling

if (hostAndPort == null && socketFactory == null) {
  throw new IllegalArgumentException("Provide hostAndPort or socketFactory before build()");
}
RedisClient client = RedisClient.builder().hostAndPort(host, port).build();

Try / catch

try {
  RedisClient client = RedisClient.builder()...build();
} catch (IllegalStateException e) {
  // log missing endpoint configuration and abort startup
}

Prevention

Always call .hostAndPort(...) first in builder chains
Load the host from config with an explicit fail-fast check before building the client
For unix-socket setups, remember a socketFactory must be supplied instead

When it happens

Trigger: Building a client via RedisClient/AbstractClientBuilder without calling .hostAndPort(...) while also not providing .socketFactory(...); calling withDefaults() on a builder that only set config items like timeout or password.

Common situations: Copy-pasted builder code where the host line was deleted or variable is null; programmatic config assembled from environment/properties where the hostname key was missing; sentinel/cluster snippets applied to standalone builders without host setup.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/ConnectionFactory.java:108

      return new ConnectionFactory(this);
    }

    private Builder withDefaults() {
      if (jedisSocketFactory == null) {
        this.jedisSocketFactory = createDefaultSocketFactory();
      }
      if (connectionBuilder == null) {
        this.connectionBuilder = createDefaultConnectionBuilder();
      }
      return this;
    }

    private JedisSocketFactory createDefaultSocketFactory() {
      if (clientConfig == null) {
        clientConfig = DefaultJedisClientConfig.builder().build();
      }
      if (hostAndPort == null) {
        throw new IllegalStateException("HostAndPort is required when no socketFactory is provided");
      }
      return new DefaultJedisSocketFactory(hostAndPort, clientConfig, maintenanceController);
    }

    private Connection.Builder createDefaultConnectionBuilder() {
      Connection.Builder connBuilder = cache == null ? Connection.builder() : CacheConnection.builder(cache);
      connBuilder.socketFactory(jedisSocketFactory).clientConfig(clientConfig);
      if (maintenanceController != null) {
        connBuilder.maintenanceConfig(maintenanceController.getConfig())
            .addVisitor(new MaintenanceAwareVisitor(connBuilder, maintenanceController));
      }
      return connBuilder;
    }
  }

  public static Builder builder() {
    return new Builder();
  }

View on GitHub (pinned to 6dac31d4c2)