OpenFeign/feign · error · IllegalArgumentException

name is required.

Error message

name is required.

What it means

RequestTemplate.header(String, Iterable<String>) requires a non-empty header name. This IllegalArgumentException is thrown when the name is null or the empty string; it guards against building HTTP requests with malformed headers.

Solutions

1. Supply a valid non-empty header name
2. Validate/trim header names before calling header()
3. Fix the annotation or config source producing the blank name
4. Skip adding the header entirely when the name is blank

Example fix

// before
template.header("", Collections.singletonList("application/json"));
// after
if (name != null && !name.isEmpty()) {
  template.header(name, Collections.singletonList("application/json"));
}

if (name == null || name.trim().isEmpty()) {
  throw new IllegalArgumentException("Header name must be non-empty");
}

try {
  template.header(name, values);
} catch (IllegalArgumentException e) {
  if ("name is required.".equals(e.getMessage())) {
    LOGGER.warn("Skipping blank header name");
  } else { throw e; }
}

When it happens

Trigger: Calling template.header(null, values) or template.header("", values); also reached from custom Contract/interceptor code that derives header names from annotations that are blank.

Common situations: Blank @Headers annotation values, configuration-driven header names that are empty, string splitting producing empty names (e.g. ': value'), typos in header map keys.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Invalid HTTP Method
• url values must be not be absolute.
• Method return type is not parameterized
• Wildcards are not supported for return-type parameters
• template has not been resolved.

AI-assisted analysis of OpenFeign/feign@e2a1e27560 (2026-09-10). Data as JSON: /api/errors/d62124db4000b64c. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/feign/RequestTemplate.java:741

   */
  public RequestTemplate header(String name, String... values) {
    if (values == null) {
      return appendHeader(name, Collections.emptyList());
    }

    return header(name, Arrays.asList(values));
  }

  /**
   * Specify a Header, with the specified values. Values can be literals or template expressions.
   *
   * @param name of the header.
   * @param values for this header.
   * @return a RequestTemplate for chaining.
   */
  public RequestTemplate header(String name, Iterable<String> values) {
    if (name == null || name.isEmpty()) {
      throw new IllegalArgumentException("name is required.");
    }
    if (values == null) {
      values = Collections.emptyList();
    }

    return appendHeader(name, values);
  }

  /**
   * @see RequestTemplate#headerLiteral(String, Iterable)
   */
  public RequestTemplate headerLiteral(String name, String... values) {
    if (values == null) {
      return headerLiteral(name, Collections.emptyList());
    }

    return headerLiteral(name, Arrays.asList(values));
  }

View on GitHub (pinned to e2a1e27560)