alibaba/spring-ai-alibaba · critical · RuntimeException

创建RestClient失败

Error message

创建RestClient失败

What it means

ElasticsearchConfig.restClient() wraps all failures during construction of the Elasticsearch low-level RestClient in a RuntimeException with the Chinese message "创建RestClient失败" ("Failed to create RestClient"). This happens while building the client from the configured host, credentials, and connection-pool settings; any exception (bad address, IO error during init, invalid pool config) is rethrown as this Spring bean-creation failure. Because it runs as a @Bean factory, the application context fails to start.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/config/ElasticsearchConfig.java:35

    @Bean
    public RestClient restClient(ElasticsearchProperties properties) {
        try {
            URL url = new URL(properties.getUrl());
            
            return RestClient.builder(
                    new HttpHost(url.getHost(), url.getPort(), url.getProtocol()))
                .setRequestConfigCallback(requestConfigBuilder -> 
                    requestConfigBuilder
                        .setConnectTimeout(properties.getConnectTimeout())
                        .setSocketTimeout(properties.getSocketTimeout()))
                .setHttpClientConfigCallback(httpClientBuilder -> 
                    httpClientBuilder
                        .setMaxConnTotal(properties.getConnectionPool().getMaxConnections())
                        .setMaxConnPerRoute(properties.getConnectionPool().getMaxIdleConnections()))
                .build();
        } catch (Exception e) {
            throw new RuntimeException("创建RestClient失败", e);
        }
    }

    @Bean
    public RestClientTransport elasticsearchTransport(RestClient restClient) {
        return new RestClientTransport(restClient, new JacksonJsonpMapper());
    }

    @Bean
    public ElasticsearchClient elasticsearchClient(RestClientTransport transport) {
        return new ElasticsearchClient(transport);
    }
}

View on GitHub (pinned to f82da0b50f)

Solutions

  1. Verify the Elasticsearch host/port and that the cluster is reachable (curl http://host:9200) before starting the app.
  2. Check the 'cause' chained in the RuntimeException — it contains the real failure (UnknownHost, ConnectException, etc.).
  3. Validate connection-pool settings in ElasticsearchProperties: maxConnections and maxIdleConnections must be positive and sane.
  4. Confirm config keys bind correctly (prefix, property names) so the pool values aren't null/0.
  5. If credentials/SSL are involved, confirm username/password and truststore configuration.

Example fix

// before
properties.getConnectionPool().getMaxConnections() // may be 0/null from bad config
// after
int max = properties.getConnectionPool().getMaxConnections();
if (max <= 0) { max = 30; } // sane default or fail fast with a clear validation message
Defensive patterns

Strategy: try-catch

Validate before calling

// verify ES reachability before startup
curl -fsS http://es-host:9200/_cluster/health || echo "ES unreachable"
// check pool config
assert properties.getConnectionPool().getMaxConnections() > 0;

Try / catch

try { RestClient client = restClient(); } catch (RuntimeException e) { log.error("RestClient init failed: {}", e.getCause(), e); throw e; }

Prevention

When it happens

Trigger: Calling restClient() with an unreachable/malformed Elasticsearch address, invalid connection-pool properties (e.g. maxConnections <= 0), or when the underlying apache HttpClient builder throws while applying setMaxConnTotal/setMaxConnPerRoute from ElasticsearchProperties.ConnectionPool.

Common situations: Wrong ES host/port in application.yml, Elasticsearch not running or unreachable at startup, mistyped connection-pool numbers in config, missing credentials causing connection setup failure, or config property binding producing zero/negative pool sizes.

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

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/ec195cbb822c1857. Report an issue: GitHub.