redis/jedis · error · IllegalArgumentException

At least one endpoint must be specified

Error message

At least one endpoint must be specified

What it means

MultiDbClientBuilder builds a MultiDbClient backed by MultiDbConnectionProvider, which needs a list of database endpoint configurations (primary/failover databases). createDefaultConnectionProvider() throws this IllegalArgumentException when multiDbConfig is null, has null database configs, or an empty array, because the provider has nothing to connect or fail over to.

Solutions

1. Add at least one endpoint via MultiDbConfig.builder().database(...) (and optionally additional failover databases) before build().
2. Verify you passed the MultiDbConfig to the client builder with .multiDb(config).
3. Validate config-driven endpoint lists for emptiness at application startup.

Example fix

// before
MultiDbClient client = MultiDbClient.builder()
    .multiDb(MultiDbConfig.builder().build()) // no databases
    .build(); // throws
// after
MultiDbClient client = MultiDbClient.builder()
    .multiDb(MultiDbConfig.builder()
        .database(DatabaseConfig.builder(HostAndPort.of("localhost", 6379)).connectionPoolConfig(poolCfg).build())
        .build())
    .build();

if (config == null || config.getDatabaseConfigs() == null || config.getDatabaseConfigs().length < 1) {
  throw new IllegalArgumentException("MultiDbConfig requires at least one database endpoint");
}

try {
  client = MultiDbClient.builder().multiDb(config).build();
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("At least one endpoint")) {
    throw new ConfigurationException("no multi-db endpoints configured", e);
  }
  throw e;
}

When it happens

Trigger: Building a MultiDbClient without calling .multiDb(MultiDbConfig) or with a MultiDbConfig whose databaseConfigs array is empty (no .database(...) endpoints added), then build() reaching createDefaultConnectionProvider().

Common situations: Forgetting to add any database endpoint to the MultiDbConfig; conditionally adding endpoints from config and ending up with an empty array; constructing the builder without the multiDbConfig field set.

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/d6df26f0d1047772. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/redis/clients/jedis/builders/MultiDbClientBuilder.java:116

   * @param listener the database switch event listener
   * @return this builder
   */
  public MultiDbClientBuilder<C> databaseSwitchListener(Consumer<DatabaseSwitchEvent> listener) {
    this.databaseSwitchListener = listener;
    return this;
  }

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

  @Override
  protected ConnectionProvider createDefaultConnectionProvider() {

    if (this.multiDbConfig == null || this.multiDbConfig.getDatabaseConfigs() == null
        || this.multiDbConfig.getDatabaseConfigs().length < 1) {
      throw new IllegalArgumentException("At least one endpoint must be specified");
    }

    // Create the multi-database connection provider
    MultiDbConnectionProvider provider = new MultiDbConnectionProvider(multiDbConfig, cache);

    // Set database switch listener if provided
    if (this.databaseSwitchListener != null) {
      provider.setDatabaseSwitchListener(this.databaseSwitchListener);
    }

    return provider;
  }

  @Override
  protected CommandExecutor createDefaultCommandExecutor() {
    // For multi-db clients, we always use MultiDbCommandExecutor
    return new MultiDbCommandExecutor((MultiDbConnectionProvider) this.connectionProvider);
  }

View on GitHub (pinned to 6dac31d4c2)