apache/druid · error · RuntimeException

Failed to apply webClientOptions to WebClientOptions. Check

Error message

Failed to apply webClientOptions to WebClientOptions. Check that all property names and values are valid. Properties provided: %s

What it means

Thrown by DruidKubernetesVertxHttpClientFactory.additionalConfig when applying the configured webClientOptions map onto the Vert.x WebClientOptions object via Jackson's objectMapper.updateValue fails. It wraps the underlying exception and tells the operator that some property name or value in druid.client.http.webClientOptions (or equivalent HttpClientConfig.webClientOptions) is not a valid settable property of WebClientOptions.

Source

Thrown at extensions-core/kubernetes-overlord-extensions/src/main/java/org/apache/druid/k8s/overlord/common/httpclient/vertx/DruidKubernetesVertxHttpClientFactory.java:63

      DruidKubernetesVertxHttpClientConfig httpClientConfig,
      ObjectMapper objectMapper
  )
  {
    super(createVertxInstance(httpClientConfig));
    this.httpClientConfig = httpClientConfig;
    this.objectMapper = objectMapper;
  }

  @Override
  protected void additionalConfig(WebClientOptions options)
  {
    if (!httpClientConfig.getWebClientOptions().isEmpty()) {
      try {
        LOG.info("Applying additional WebClientOptions from configuration: %s", httpClientConfig.getWebClientOptions());
        objectMapper.updateValue(options, httpClientConfig.getWebClientOptions());
      }
      catch (Exception e) {
        throw new RuntimeException(
            "Failed to apply webClientOptions to WebClientOptions. "
            + "Check that all property names and values are valid. "
            + "Properties provided: " + httpClientConfig.getWebClientOptions(),
            e
        );
      }
    }
  }

  /**
   * Adapted from fabric8 kubernetes-client 7.1.0. We bring this here so we can customize thread pool sizes
   * and force usage of daemon threads.
   */
  private static Vertx createVertxInstance(final DruidKubernetesVertxHttpClientConfig httpClientConfig)
  {
    // fabric8 disables the async DNS resolver while creating Vertx.
    // I'm not sure if we really need to do this, but I'm keeping it to align behavior with upstream.
    final String originalDnsResolverProperty = System.getProperty(ResolverProvider.DISABLE_DNS_RESOLVER_PROP_NAME);

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Read the wrapped cause in the exception stack trace to find the exact offending property, then fix or remove it from the webClientOptions map
2. Validate each key against the WebClientOptions setter list for the Vert.x version bundled with your Druid build
3. Check value types (numeric/boolean options must be the right JSON type)
4. If a key exists only in newer Vert.x, remove it until upgrading Druid

Example fix

// before (invalid/misspelled option)
druid.client.http.webClientOptions='{"connectTimout": 5000}'

// after
druid.client.http.webClientOptions='{"setConnectTimeout": 5000}'

// Validate webClientOptions keys against WebClientOptions setters before configuring
ObjectMapper om = new ObjectMapper();
WebClientOptions probe = new WebClientOptions();
for (String key : httpClientConfig.getWebClientOptions().keySet()) {
    // updateValue on a throwaway instance to detect bad keys early
    try {
        om.updateValue(probe, Map.of(key, httpClientConfig.getWebClientOptions().get(key)));
    } catch (Exception e) {
        throw new IllegalArgumentException("Invalid webClientOptions key: " + key, e);
    }
}

try {
    httpClientFactory.applyConfig(options);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Failed to apply webClientOptions")) {
        LOG.error(e, "Bad druid.client.http.webClientOptions; starting client with defaults");
        // fall back to default options instead of aborting startup
    } else {
        throw e;
    }
}

When it happens

Trigger: HttpClientConfig.getWebClientOptions() is non-empty and objectMapper.updateValue(options, webClientOptions) throws — typically an unknown option key (typo or property not existing in the Vert.x version in use) or a value of the wrong type (e.g. string where an int/boolean is required).

Common situations: Typos in option names like 'connectTimeout' vs actual Vert.x property names; options introduced in newer Vert.x versions than the one bundled with this Druid build; passing nested structures as flat strings; copy-pasting options from io.vertx.core.http.HttpClientOptions (old class) that no longer exist on WebClientOptions.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• S3StorageConfig cannot be null!
• Failed to merge existing aggregators when generating metrics
• No segments found for compaction. Please check that datasour
• DynamicPartitionsSpec must be used for best-effort rollup
• Unable to create RecordSupplier: %s

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/b90634c268059bcf. Report an issue: GitHub.