eclipse-vertx/vert.x · error · IllegalArgumentException

Invalid setting

Error message

Invalid setting

What it means

HttpSettings.get() only works for settings applicable to the HttpVersion of this settings object (HTTP/1.x, HTTP/2, or HTTP/3). Each HttpSetting declares which protocol versions support it; if the current version is not among setting.versions, the lookup is invalid and Vert.x throws this IllegalArgumentException rather than returning a misleading null.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/HttpSettings.java:67

   * @return a reference to this, so the API can be used fluently
   */
  public <T> HttpSettings set(HttpSetting<T> setting, T value) {
    if (value == null) {
      throw new NullPointerException("No null value accepted");
    }
    return setLong(setting, setting.to.convert(value));
  }

  /**
   * Get the {@code setting } value as {@code <T>}.
   *
   * @param setting the setting
   * @return the value or {@code null} if the value is not present
   */
  public <T> T get(HttpSetting<T> setting) {
    HttpVersion version = version();
    if (!setting.versions.contains(version)) {
      throw new IllegalArgumentException("Invalid setting");
    }
    Long value = getLong(setting);
    return value != null ? setting.from.convert(value) : null;
  }

  /**
   * Get the {@code setting } value as {@code <T>}.
   *
   * @param setting the setting
   * @return the value, which is never {@code null} since the setting default value will be returned instead
   */
  public <T> T getOrDefault(HttpSetting<T> setting) {
    HttpVersion version = version();
    if (!setting.versions.contains(version)) {
      throw new IllegalArgumentException("Invalid setting");
    }
    long value = getLongOrDefault(setting);
    return setting.from.convert(value);

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Check that the setting applies to the settings version before reading: verify the HttpSetting was declared for the active HttpVersion (e.g. only use Http2Settings.* entries on HTTP/2 settings).
2. Filter the setting list by version support before iterating, e.g. skip settings whose supported versions do not contain settings.version().
3. If you need a value across protocols, read it from a settings object with the matching version.

Example fix

// before
Long v = settings.get(Http2Settings.HTTP2_MAX_FRAME_SIZE); // settings is HTTP/1.x
// after
if (settings.version() == HttpVersion.HTTP_2) {
  Long v = settings.get(Http2Settings.HTTP2_MAX_FRAME_SIZE);
}

if (settings.version() != null && setting.supportedVersions().contains(settings.version())) {
  Long v = settings.get(setting);
}

boolean isApplicable(HttpSettings s, HttpSetting<?> st) { return st.supportedVersions().contains(s.version()); }

try { Long v = settings.get(setting); } catch (IllegalArgumentException e) { /* setting not valid for this protocol version */ }

When it happens

Trigger: Calling httpSettings.get(someHttp2Setting) (e.g. Http2Settings.HTTP2_MAX_FRAME_SIZE) on a settings object whose version() is HTTP/1.x, or vice versa, e.g. querying an HTTP/2-only setting on a client configured for HTTP/1.1.

Common situations: Reading client settings generically over a list of HttpSettings without checking protocol version; sharing a settings object between an HTTP/1.1 client and an HTTP/2 client; tests like testClientSettings querying settings across versions.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• code: <statusCode> (expected: 0+)
• Unsupported HTTP version: <version>
• size must be > 0
• maxExecuteTime must be > 0
• Unit must not be null

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/7150f38a1dd6efaa. Report an issue: GitHub.