OpenFeign/feign · error · IllegalArgumentException

name is required.

Error message

name is required.

What it means

HeaderTemplate.create builds a template for a single HTTP header from a name and value collection. The header name is mandatory because Feign cannot emit a header line without one, so a null or empty name is rejected with this IllegalArgumentException at template creation time. It surfaces when calling create directly or via HeaderTemplate.append.

Solutions

1. Always pass a non-null, non-empty header name to create/append.
2. Guard config lookups for header names and fall back to a default or skip the header.
3. Validate header names before building the request template.
4. Skip adding the header entirely when the configured name is blank.

Example fix

// before
HeaderTemplate.create(config.getHeaderName(), values); // name may be null
// after
if (config.getHeaderName() != null && !config.getHeaderName().isEmpty()) {
  HeaderTemplate.create(config.getHeaderName(), values);
}

if (headerName == null || headerName.isEmpty()) {
  throw new IllegalArgumentException("header name must be non-empty before building template");
}
HeaderTemplate.create(headerName, values);

static boolean validHeaderName(String n) { return n != null && !n.isEmpty(); }

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

When it happens

Trigger: Calling HeaderTemplate.create(null, values) or create("", values); a config-derived header name that is missing/empty; append(null, ...) on an existing HeaderTemplate; variable substitution producing an empty header name.

Common situations: Header names read from properties/env vars that are unset; loop-built headers where one key is blank; refactoring that drops the constant header name argument.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• values are required
• Status Code [ ] has already been declared to throw [ ] and…
• Cannot generate exception - check constructor parameter…
• Too many constructors marked with @FeignExceptionConstructor
• Cannot find any suitable constructor in class

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

Appendix: source

Thrown at core/src/main/java/feign/template/HeaderTemplate.java:43

import java.util.LinkedHashSet;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CopyOnWriteArrayList;
import java.util.stream.Collectors;
import java.util.stream.StreamSupport;

/**
 * Template for HTTP Headers. Variables that are unresolved are ignored and Literals are not
 * encoded.
 */
public final class HeaderTemplate {

  private final String name;
  private final List<Template> values = new CopyOnWriteArrayList<>();

  public static HeaderTemplate create(String name, Iterable<String> values) {
    if (name == null || name.isEmpty()) {
      throw new IllegalArgumentException("name is required.");
    }

    if (values == null) {
      throw new IllegalArgumentException("values are required");
    }

    return new HeaderTemplate(name, values, Util.UTF_8);
  }

  public static HeaderTemplate literal(String name, Iterable<String> values) {
    if (name == null || name.isEmpty()) {
      throw new IllegalArgumentException("name is required.");
    }

    if (values == null) {
      throw new IllegalArgumentException("values are required");
    }

View on GitHub (pinned to e2a1e27560)