redis/jedis · error · IllegalArgumentException

Either URI or host/port must be specified

Error message

Either URI or host/port must be specified

What it means

StandaloneClientBuilder needs a target Redis endpoint: either a HostAndPort or a URI. validateSpecificConfiguration() throws this IllegalArgumentException when hostAndPort is still null at build() time, meaning neither a host/port/endpoint nor a URI was supplied (the builder stores URI-derived values into hostAndPort).

Solutions

1. Add .hostAndPort("localhost", 6379) (or .endpoint(...) / .uri("redis://localhost:6379")) before build().
2. If using .uri(String), verify the string parses correctly and the call precedes build().
3. Ensure exactly one address-setting path in conditional code always sets an endpoint; validate at startup.

Example fix

// before
RedisClient client = RedisClient.builder()
    .clientConfig(ClientConfig.builder().resp3().build())
    .build(); // throws: no endpoint
// after
RedisClient client = RedisClient.builder()
    .hostAndPort("localhost", 6379)
    .clientConfig(ClientConfig.builder().resp3().build())
    .build();

if (hostAndPort == null && uri == null) {
  throw new IllegalArgumentException("set hostAndPort or uri for the Redis endpoint");
}

try {
  client = RedisClient.builder().hostAndPort(host, port).build();
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Either URI or host/port")) {
    throw new ConfigurationException("redis endpoint missing", e);
  }
  throw e;
}

When it happens

Trigger: Building a RedisClient without calling .hostAndPort(...), .endpoint(...), or .uri(...) / .uri(String), so no address was recorded before build().

Common situations: Constructing the builder conditionally and skipping all address setters when a config branch doesn't match; passing a malformed URI string to .uri(String) expecting it to be parsed later; copy-pasted builder code where the .hostAndPort line was deleted.

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

• HostAndPort is required when no socketFactory is provided
• Client-side caching is only supported with RESP3.
• At least one cluster node must be specified for cluster mode
• Max attempts must be positive for cluster mode
• Max total retries duration cannot be negative for cluster…

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

Appendix: source

Thrown at src/main/java/redis/clients/jedis/builders/StandaloneClientBuilder.java:85

  }

  @Override
  protected StandaloneClientBuilder<C> self() {
    return this;
  }

  @Override
  protected ConnectionProvider createDefaultConnectionProvider() {
    return new PooledConnectionProvider(this.hostAndPort, this.clientConfig, this.cache,
        this.poolConfig, this.maintNotificationsConfig);
  }

  @Override
  protected void validateSpecificConfiguration() {
    validateCommonConfiguration();

    if (hostAndPort == null) {
      throw new IllegalArgumentException("Either URI or host/port must be specified");
    }
  }

  /**
   * Sets the Redis server URI from a string.
   * <p>
   * This method extracts connection parameters from the URI and merges them into the current client
   * configuration. If a client configuration was previously set via
   * {@link #clientConfig(JedisClientConfig)}, only the values explicitly provided in the URI will
   * override the existing configuration. Values not present in the URI will be preserved from the
   * existing configuration.
   * <p>
   * <b>This method sets:</b>
   * <ul>
   * <li>Host and port from the URI (always set)</li>
   * <li>Client configuration with URI-derived values (merged with existing config if present)</li>
   * </ul>
   * <p>

View on GitHub (pinned to 6dac31d4c2)